Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / clang / 5d46db8882002c09c988b021b38c2334aa23f535 / . / docs / HowToSetupToolingForLLVM.html
blob: 493c8820fc4f6a032e4b358d8dbc7eede2a1c69d [file] [log] [blame]
Alexander Kornienkoa7f2c562012-07-11 14:27:44 +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>How To Setup Clang Tooling For LLVM</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>
10
11<!--#include virtual="../menu.html.incl"-->
12
13<div id="content">
14
15<h1>How To Setup Clang Tooling For LLVM</h1>
16<p>Clang Tooling provides infrastructure to write tools that need syntactic and
17semantic infomation about a program. This term also relates to a set of specific
18tools using this infrastructure (e.g. <code>clang-check</code>). This document
19provides information on how to set up and use Clang Tooling for the LLVM source
20code.</p>
21
22
23<!-- ======================================================================= -->
24<h2><a name="introduction">Introduction</a></h2>
25<!-- ======================================================================= -->
26
27<p>Clang Tooling needs a compilation database to figure out specific build
28options for each file. Currently it can create a compilation database from the
29<code>compilation_commands.json</code> file, generated by CMake. When invoking
30clang tools, you can either specify a path to a build directory using a command
31line parameter <code>-p</code> or let Clang Tooling find this file in your
32source tree. In either case you need to configure your build using CMake to use
33clang tools.</p>
34
35<!-- ======================================================================= -->
36<h2><a name="using-make">Setup Clang Tooling Using CMake and Make</a></h2>
37<!-- ======================================================================= -->
38
39<p>If you intend to use make to build LLVM, you should have CMake 2.8.6 or later
40installed (can be found <a href="http://cmake.org">here</a>).</p>
41<p>First, you need to generate Makefiles for LLVM with CMake. You need to make
42a build directory and run CMake from it:</p>
43<pre>
44 mkdir your/build/directory
45 cd your/build/directory
46 cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON path/to/llvm/sources
47</pre>
48
49<p>If you want to use clang instead of GCC, you can add
50<code>-DCMAKE_C_COMPILER=/path/to/clang
51 -DCMAKE_CXX_COMPILER=/path/to/clang++</code>.
52You can also use ccmake, which provides a curses interface to configure CMake
53variables for lazy people.</p>
54
55<p>As a result, the new <code>compile_commands.json</code> file should appear in
56the current directory. You should link it to the LLVM source tree so that Clang
57Tooling is able to use it:</p>
58<pre>
59 ln -s $PWD/compile_commands.json path/to/llvm/source/
60</pre>
61
62<p>Now you are ready to build and test LLVM using make:</p>
63<pre>
64 make check-all
65</pre>
66
67<!-- ======================================================================= -->
68<h2><a name="using-tools">Using Clang Tools</a></h2>
69<!-- ======================================================================= -->
70
71<p>After you completed the previous steps, you are ready to run clang tools. If
72you have a recent clang installed, you should have <code>clang-check</code> in
73$PATH. Try to run it on any .cpp file inside the LLVM source tree:</p>
74<pre>
75 clang-check tools/clang/lib/Tooling/CompilationDatabase.cpp
76</pre>
77<p>If you're using vim, it's convenient to have clang-check integrated. Put this
78into your .vimrc:</p>
79<pre>
80 set makeprg=clang-check\ %
81 map &lt;F5&gt; :make&lt;CR&gt;&lt;CR&gt;
82</pre>
83
84<p>When editing C++ code, hit F5 to reparse the current buffer. The output will
85go into the error window, which you can enable with <code>:cope</code>.</p>
86
Alexander Kornienko5d46db82012-08-14 08:31:51 +0000[diff] [blame^]87<p>Other <code>clang-check</code> options that can be useful when working with
88clang AST:</p>
89<ul>
90 <li><code>-ast-print</code> - Build ASTs and then pretty-print them.</li>
91 <li><code>-ast-dump</code> - Build ASTs and then debug dump them.</li>
92 <li><code>-ast-dump-filter=&lt;string&gt;</code> - Use with
93 <code>-ast-dump</code> or <code>-ast-print</code> to dump/print
94 only AST declaration nodes having a certain substring in a qualified name.
95 Use <code>-ast-list</code> to list all filterable declaration node
96 names.</li>
97 <li><code>-ast-list</code> - Build ASTs and print the list of declaration
98 node qualified names.</li>
99</ul>
100<p>Examples:</p>
101<pre>
102<b>$ clang-check tools/clang/tools/clang-check/ClangCheck.cpp -ast-dump -ast-dump-filter ActionFactory::newASTConsumer</b>
103Processing: tools/clang/tools/clang-check/ClangCheck.cpp.
104Dumping <anonymous namespace>::ActionFactory::newASTConsumer:
105clang::ASTConsumer *newASTConsumer() (CompoundStmt 0x44da290 &lt;/home/alexfh/local/llvm/tools/clang/tools/clang-check/ClangCheck.cpp:64:40, line:72:3&gt;
106 (IfStmt 0x44d97c8 &lt;line:65:5, line:66:45&gt;
107 &lt;&lt;&lt;NULL&gt;&gt;&gt;
108 (ImplicitCastExpr 0x44d96d0 &lt;line:65:9&gt; '_Bool':'_Bool' &lt;UserDefinedConversion&gt;
109...
110<b>$ clang-check tools/clang/tools/clang-check/ClangCheck.cpp -ast-print -ast-dump-filter ActionFactory::newASTConsumer</b>
111Processing: tools/clang/tools/clang-check/ClangCheck.cpp.
112Printing &lt;anonymous namespace&gt;::ActionFactory::newASTConsumer:
113clang::ASTConsumer *newASTConsumer() {
114 if (this-&gt;ASTList.operator _Bool())
115 return clang::CreateASTDeclNodeLister();
116 if (this-&gt;ASTDump.operator _Bool())
117 return clang::CreateASTDumper(this-&gt;ASTDumpFilter);
118 if (this-&gt;ASTPrint.operator _Bool())
119 return clang::CreateASTPrinter(&amp;llvm::outs(), this-&gt;ASTDumpFilter);
120 return new clang::ASTConsumer();
121}
122</pre>
Alexander Kornienkoa7f2c562012-07-11 14:27:44 +0000[diff] [blame]123
124<!-- ======================================================================= -->
125<h2><a name="using-ninja">(Experimental) Using Ninja Build System</a></h2>
126<!-- ======================================================================= -->
127
128<p>Optionally you can use the <a
129 href="https://github.com/martine/ninja">Ninja</a> build system instead of
130make. It is aimed at making your builds faster. Currently this step will require
131building Ninja from sources and using a development version of CMake.</p>
132<p>To take advantage of using Clang Tools along with Ninja build you need at
133least CMake 2.8.9. At the moment CMake 2.8.9 is still under development, so you
134can get latest development sources and build it yourself:</p>
135<pre>
136 git clone git://cmake.org/cmake.git
137 cd cmake
138 ./bootstrap
139 make
140 sudo make install
141</pre>
142
143<p>Having the correct version of CMake, you can clone the Ninja git repository
144and build Ninja from sources:</p>
145<pre>
146 git clone git://github.com/martine/ninja.git
147 cd ninja/
148 ./bootstrap.py
149</pre>
150<p>This will result in a single binary <code>ninja</code> in the current
151directory. It doesn't require installation and can just be copied to any
152location inside <code>$PATH</code>, say <code>/usr/local/bin/</code>:</p>
153<pre>
154 sudo cp ninja /usr/local/bin/
155 sudo chmod a+rx /usr/local/bin/ninja
156</pre>
157<p>After doing all of this, you'll need to generate Ninja build files for LLVM
158with CMake. You need to make a build directory and run CMake from it:</p>
159<pre>
160 mkdir your/build/directory
161 cd your/build/directory
162 cmake -G Ninja -DCMAKE_EXPORT_COMPILE_COMMANDS=ON path/to/llvm/sources
163</pre>
164
165<p>If you want to use clang instead of GCC, you can add
166<code>-DCMAKE_C_COMPILER=/path/to/clang
167 -DCMAKE_CXX_COMPILER=/path/to/clang++</code>.
168You can also use ccmake, which provides a curses interface to configure CMake
169variables in an interactive manner.</p>
170
171<p>As a result, the new <code>compile_commands.json</code> file should appear in
172the current directory. You should link it to the LLVM source tree so that Clang
173Tooling is able to use it:</p>
174<pre>
175 ln -s $PWD/compile_commands.json path/to/llvm/source/
176</pre>
177
178<p>Now you are ready to build and test LLVM using Ninja:</p>
179<pre>
180 ninja check-all
181</pre>
182<p>Other target names can be used in the same way as with make.</p>
183</div>
184</body>
185</html>
186