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