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