Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / external / clang / c5e3df7d9951502fe016445f1c93dc9a3efea4df / . / docs / Tooling.html
blob: 74837f4c99b99891444498f75cae5f70fd7157b0 [file] [log] [blame]
Manuel Klimek9771a9e2012-04-25 13:57:00 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
3<html>
4<head>
5<title>Writing Clang Tools</title>
6<link type="text/css" rel="stylesheet" href="../menu.css">
7<link type="text/css" rel="stylesheet" href="../content.css">
8</head>
9<body>
Manuel Klimek0fe1e1f2012-05-24 17:09:10 +0000[diff] [blame]10
11<!--#include virtual="../menu.html.incl"-->
12
Manuel Klimek9771a9e2012-04-25 13:57:00 +0000[diff] [blame]13<div id="content">
14
15<h1>Writing Clang Tools</h1>
16<p>Clang provides infrastructure to write tools that need syntactic and semantic
17information about a program. This document will give a short introduction of the
18different ways to write clang tools, and their pros and cons.</p>
19
20<!-- ======================================================================= -->
21<h2 id="libclang"><a href="http://clang.llvm.org/doxygen/group__CINDEX.html">LibClang</a></h2>
22<!-- ======================================================================= -->
23
24<p>LibClang is a stable high level C interface to clang. When in doubt LibClang
25is probably the interface you want to use. Consider the other interfaces only
26when you have a good reason not to use LibClang.</p>
27<p>Canonical examples of when to use LibClang:</p>
28<ul>
Jean-Daniel Dupas332f9aa2012-05-13 14:32:11 +0000[diff] [blame]29 <li>Xcode</li>
Manuel Klimek9771a9e2012-04-25 13:57:00 +0000[diff] [blame]30 <li>Clang Python Bindings</li>
31</ul>
32<p>Use LibClang when you...</p>
33<ul>
34 <li>want to interface with clang from other languages than C++</li>
35 <li>need a stable interface that takes care to be backwards compatible</li>
Benjamin Kramer48d798c2012-06-02 10:20:41 +0000[diff] [blame]36 <li>want powerful high-level abstractions, like iterating through an AST
Manuel Klimek9771a9e2012-04-25 13:57:00 +0000[diff] [blame]37with a cursor, and don't want to learn all the nitty gritty details of Clang's
38AST.</li>
39</ul>
40<p>Do not use LibClang when you...</p>
41<ul>
42 <li>want full control over the Clang AST</li>
43</ul>
44
45<!-- ======================================================================= -->
Manuel Klimek0fe1e1f2012-05-24 17:09:10 +0000[diff] [blame]46<h2 id="clang-plugins"><a href="ClangPlugins.html">Clang Plugins</a></h2>
Manuel Klimek9771a9e2012-04-25 13:57:00 +0000[diff] [blame]47<!-- ======================================================================= -->
48
49<p>Clang Plugins allow you to run additional actions on the AST as part of
50a compilation. Plugins are dynamic libraries that are loaded at runtime by
51the compiler, and they're easy to integrate into your build environment.</p>
52<p>Canonical examples of when to use Clang Plugins:</p>
53<ul>
54 <li>special lint-style warnings or errors for your project</li>
55 <li>creating additional build artifacts from a single compile step</li>
56</ul>
57<p>Use Clang Plugins when you...</p>
58<ul>
59 <li>need your tool to rerun if any of the dependencies change</li>
60 <li>want your tool to make or break a build</li>
61 <li>need full control over the Clang AST</li>
62</ul>
63<p>Do not use Clang Plugins when you...</p>
64<ul>
65 <li>want to run tools outside of your build environment</li>
66 <li>want full control on how Clang is set up, including mapping of in-memory
67 virtual files</li>
68 <li>need to run over a specific subset of files in your project which is not
69 necessarily related to any changes which would trigger rebuilds</li>
70</ul>
71
72<!-- ======================================================================= -->
Manuel Klimek0fe1e1f2012-05-24 17:09:10 +0000[diff] [blame]73<h2 id="libtooling"><a href="LibTooling.html">LibTooling</a></h2>
Manuel Klimek9771a9e2012-04-25 13:57:00 +0000[diff] [blame]74<!-- ======================================================================= -->
75
76<p>LibTooling is a C++ interface aimed at writing standalone tools, as well as
77integrating into services that run clang tools.</p>
78<p>Canonical examples of when to use LibTooling:</p>
79<ul>
80 <li>a simple syntax checker</li>
81 <li>refactoring tools</li>
82</ul>
83<p>Use LibTooling when you...</p>
84<ul>
85 <li>want to run tools over a single file, or a specific subset of files,
86 independently of the build system</li>
87 <li>want full control over the Clang AST</li>
88 <li>want to share code with Clang Plugins</li>
89</ul>
90<p>Do not use LibTooling when you...</p>
91<ul>
92 <li>want to run as part of the build triggered by dependency changes</li>
93 <li>want a stable interface so you don't need to change your code when the
94 AST API changes</li>
95 <li>want high level abstractions like cursors and code completion out of the
96 box</li>
97 <li>do not want to write your tools in C++</li>
98</ul>
99
Chandler Carruthe56f3a62012-08-14 07:19:09 +0000[diff] [blame]100<!-- ======================================================================= -->
101<h2 id="clang-tools"><a href="ClangTools.html">Clang Tools</a></h2>
102<!-- ======================================================================= -->
103
104<p>These are a collection of specific developer tools built on top of the
105LibTooling infrastructure as part of the Clang project. They are targeted at
106automating and improving core development activities of C/C++ developers.</p>
107<p>Examples of tools we are building or planning as part of the Clang
108project:</p>
109<ul>
110 <li>Syntax checking (clang-check)</li>
111 <li>Automatic fixing of compile errors (clangc-fixit)</li>
112 <li>Automatic code formatting</li>
113 <li>Migration tools for new features in new language standards</li>
114 <li>Core refactoring tools</li>
115</ul>
116
Manuel Klimek9771a9e2012-04-25 13:57:00 +0000[diff] [blame]117</div>
118</body>
119</html>
120