Clang Project

clang_source_code/docs/HowToSetupToolingForLLVM.rst
1===================================
2How To Setup Clang Tooling For LLVM
3===================================
4
5Clang Tooling provides infrastructure to write tools that need syntactic
6and semantic information about a program. This term also relates to a set
7of specific tools using this infrastructure (e.g. ``clang-check``). This
8document provides information on how to set up and use Clang Tooling for
9the LLVM source code.
10
11Introduction
12============
13
14Clang Tooling needs a compilation database to figure out specific build
15options for each file. Currently it can create a compilation database
16from the ``compile_commands.json`` file, generated by CMake. When
17invoking clang tools, you can either specify a path to a build directory
18using a command line parameter ``-p`` or let Clang Tooling find this
19file in your source tree. In either case you need to configure your
20build using CMake to use clang tools.
21
22Setup Clang Tooling Using CMake and Make
23========================================
24
25If you intend to use make to build LLVM, you should have CMake 2.8.6 or
26later installed (can be found `here <https://cmake.org>`_).
27
28First, you need to generate Makefiles for LLVM with CMake. You need to
29make 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
37If you want to use clang instead of GCC, you can add
38``-DCMAKE_C_COMPILER=/path/to/clang -DCMAKE_CXX_COMPILER=/path/to/clang++``.
39You can also use ``ccmake``, which provides a curses interface to configure
40CMake variables for lazy people.
41
42As a result, the new ``compile_commands.json`` file should appear in the
43current directory. You should link it to the LLVM source tree so that
44Clang Tooling is able to use it:
45
46.. code-block:: console
47
48  $ ln -s $PWD/compile_commands.json path/to/llvm/source/
49
50Now you are ready to build and test LLVM using make:
51
52.. code-block:: console
53
54  $ make check-all
55
56Using Clang Tools
57=================
58
59After you completed the previous steps, you are ready to run clang tools. If
60you 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
67If you're using vim, it's convenient to have clang-check integrated. Put
68this 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
98When editing a .cpp/.cxx/.cc/.c file, hit F5 to reparse the file. In
99case the current file has a different extension (for example, .h), F5
100will 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
102automatically when clang-check finds errors, and can be re-opened with
103``:cope``.
104
105Other ``clang-check`` options that can be useful when working with clang
106AST:
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
117Examples:
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(Experimental) Using Ninja Build System
144=======================================
145
146Optionally you can use the `Ninja <https://github.com/martine/ninja>`_
147build system instead of make. It is aimed at making your builds faster.
148Currently this step will require building Ninja from sources.
149
150To take advantage of using Clang Tools along with Ninja build you need
151at least CMake 2.8.9.
152
153Clone 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
161This will result in a single binary ``ninja`` in the current directory.
162It doesn't require installation and can just be copied to any location
163inside ``$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
170After doing all of this, you'll need to generate Ninja build files for
171LLVM with CMake. You need to make a build directory and run CMake from
172it:
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
180If you want to use clang instead of GCC, you can add
181``-DCMAKE_C_COMPILER=/path/to/clang -DCMAKE_CXX_COMPILER=/path/to/clang++``.
182You can also use ``ccmake``, which provides a curses interface to configure
183CMake variables in an interactive manner.
184
185As a result, the new ``compile_commands.json`` file should appear in the
186current directory. You should link it to the LLVM source tree so that
187Clang Tooling is able to use it:
188
189.. code-block:: console
190
191  $ ln -s $PWD/compile_commands.json path/to/llvm/source/
192
193Now you are ready to build and test LLVM using Ninja:
194
195.. code-block:: console
196
197  $ ninja check-all
198
199Other target names can be used in the same way as with make.
200
201
CodeThinker, Enjoy your reading code