diff options
Diffstat (limited to 'docs/Tooling.html')
| -rw-r--r-- | docs/Tooling.html | 120 |
1 files changed, 120 insertions, 0 deletions
diff --git a/docs/Tooling.html b/docs/Tooling.html new file mode 100644 index 0000000..74837f4 --- /dev/null +++ b/docs/Tooling.html @@ -0,0 +1,120 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> +<html> +<head> +<title>Writing Clang Tools</title> +<link type="text/css" rel="stylesheet" href="../menu.css"> +<link type="text/css" rel="stylesheet" href="../content.css"> +</head> +<body> + +<!--#include virtual="../menu.html.incl"--> + +<div id="content"> + +<h1>Writing Clang Tools</h1> +<p>Clang provides infrastructure to write tools that need syntactic and semantic +information about a program. This document will give a short introduction of the +different ways to write clang tools, and their pros and cons.</p> + +<!-- ======================================================================= --> +<h2 id="libclang"><a href="http://clang.llvm.org/doxygen/group__CINDEX.html">LibClang</a></h2> +<!-- ======================================================================= --> + +<p>LibClang is a stable high level C interface to clang. When in doubt LibClang +is probably the interface you want to use. Consider the other interfaces only +when you have a good reason not to use LibClang.</p> +<p>Canonical examples of when to use LibClang:</p> +<ul> + <li>Xcode</li> + <li>Clang Python Bindings</li> +</ul> +<p>Use LibClang when you...</p> +<ul> + <li>want to interface with clang from other languages than C++</li> + <li>need a stable interface that takes care to be backwards compatible</li> + <li>want powerful high-level abstractions, like iterating through an AST +with a cursor, and don't want to learn all the nitty gritty details of Clang's +AST.</li> +</ul> +<p>Do not use LibClang when you...</p> +<ul> + <li>want full control over the Clang AST</li> +</ul> + +<!-- ======================================================================= --> +<h2 id="clang-plugins"><a href="ClangPlugins.html">Clang Plugins</a></h2> +<!-- ======================================================================= --> + +<p>Clang Plugins allow you to run additional actions on the AST as part of +a compilation. Plugins are dynamic libraries that are loaded at runtime by +the compiler, and they're easy to integrate into your build environment.</p> +<p>Canonical examples of when to use Clang Plugins:</p> +<ul> + <li>special lint-style warnings or errors for your project</li> + <li>creating additional build artifacts from a single compile step</li> +</ul> +<p>Use Clang Plugins when you...</p> +<ul> + <li>need your tool to rerun if any of the dependencies change</li> + <li>want your tool to make or break a build</li> + <li>need full control over the Clang AST</li> +</ul> +<p>Do not use Clang Plugins when you...</p> +<ul> + <li>want to run tools outside of your build environment</li> + <li>want full control on how Clang is set up, including mapping of in-memory + virtual files</li> + <li>need to run over a specific subset of files in your project which is not + necessarily related to any changes which would trigger rebuilds</li> +</ul> + +<!-- ======================================================================= --> +<h2 id="libtooling"><a href="LibTooling.html">LibTooling</a></h2> +<!-- ======================================================================= --> + +<p>LibTooling is a C++ interface aimed at writing standalone tools, as well as +integrating into services that run clang tools.</p> +<p>Canonical examples of when to use LibTooling:</p> +<ul> + <li>a simple syntax checker</li> + <li>refactoring tools</li> +</ul> +<p>Use LibTooling when you...</p> +<ul> + <li>want to run tools over a single file, or a specific subset of files, + independently of the build system</li> + <li>want full control over the Clang AST</li> + <li>want to share code with Clang Plugins</li> +</ul> +<p>Do not use LibTooling when you...</p> +<ul> + <li>want to run as part of the build triggered by dependency changes</li> + <li>want a stable interface so you don't need to change your code when the + AST API changes</li> + <li>want high level abstractions like cursors and code completion out of the + box</li> + <li>do not want to write your tools in C++</li> +</ul> + +<!-- ======================================================================= --> +<h2 id="clang-tools"><a href="ClangTools.html">Clang Tools</a></h2> +<!-- ======================================================================= --> + +<p>These are a collection of specific developer tools built on top of the +LibTooling infrastructure as part of the Clang project. They are targeted at +automating and improving core development activities of C/C++ developers.</p> +<p>Examples of tools we are building or planning as part of the Clang +project:</p> +<ul> + <li>Syntax checking (clang-check)</li> + <li>Automatic fixing of compile errors (clangc-fixit)</li> + <li>Automatic code formatting</li> + <li>Migration tools for new features in new language standards</li> + <li>Core refactoring tools</li> +</ul> + +</div> +</body> +</html> + |
