Nikola Smiljanic | c2345a9 | 2013-01-11 07:14:58 +0000 | [diff] [blame] | 1 | =================================== |
| 2 | How To Setup Clang Tooling For LLVM |
| 3 | =================================== |
| 4 | |
| 5 | Clang Tooling provides infrastructure to write tools that need syntactic |
Nikola Smiljanic | 253de1f | 2013-01-11 07:23:53 +0000 | [diff] [blame] | 6 | and semantic information about a program. This term also relates to a set |
Nikola Smiljanic | c2345a9 | 2013-01-11 07:14:58 +0000 | [diff] [blame] | 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 ``compilation_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 <http://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 |
| 40 | CMake variables for lazy people. |
| 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(this->ASTDumpFilter); |
| 137 | if (this->ASTPrint.operator _Bool()) |
| 138 | return clang::CreateASTPrinter(&llvm::outs(), this->ASTDumpFilter); |
| 139 | return new clang::ASTConsumer(); |
| 140 | } |
| 141 | |
| 142 | (Experimental) Using Ninja Build System |
| 143 | ======================================= |
| 144 | |
| 145 | Optionally you can use the `Ninja <https://github.com/martine/ninja>`_ |
| 146 | build system instead of make. It is aimed at making your builds faster. |
Nikola Smiljanic | 253de1f | 2013-01-11 07:23:53 +0000 | [diff] [blame] | 147 | Currently this step will require building Ninja from sources. |
Nikola Smiljanic | c2345a9 | 2013-01-11 07:14:58 +0000 | [diff] [blame] | 148 | |
| 149 | To take advantage of using Clang Tools along with Ninja build you need |
Nikola Smiljanic | 253de1f | 2013-01-11 07:23:53 +0000 | [diff] [blame] | 150 | at least CMake 2.8.9. |
Nikola Smiljanic | c2345a9 | 2013-01-11 07:14:58 +0000 | [diff] [blame] | 151 | |
Nikola Smiljanic | 253de1f | 2013-01-11 07:23:53 +0000 | [diff] [blame] | 152 | Clone the Ninja git repository and build Ninja from sources: |
Nikola Smiljanic | c2345a9 | 2013-01-11 07:14:58 +0000 | [diff] [blame] | 153 | |
| 154 | .. code-block:: console |
| 155 | |
| 156 | $ git clone git://github.com/martine/ninja.git |
| 157 | $ cd ninja/ |
| 158 | $ ./bootstrap.py |
| 159 | |
| 160 | This will result in a single binary ``ninja`` in the current directory. |
| 161 | It doesn't require installation and can just be copied to any location |
| 162 | inside ``$PATH``, say ``/usr/local/bin/``: |
| 163 | |
| 164 | .. code-block:: console |
| 165 | |
| 166 | $ sudo cp ninja /usr/local/bin/ |
| 167 | $ sudo chmod a+rx /usr/local/bin/ninja |
| 168 | |
| 169 | After doing all of this, you'll need to generate Ninja build files for |
| 170 | LLVM with CMake. You need to make a build directory and run CMake from |
| 171 | it: |
| 172 | |
| 173 | .. code-block:: console |
| 174 | |
| 175 | $ mkdir your/build/directory |
| 176 | $ cd your/build/directory |
| 177 | $ cmake -G Ninja -DCMAKE_EXPORT_COMPILE_COMMANDS=ON path/to/llvm/sources |
| 178 | |
| 179 | If you want to use clang instead of GCC, you can add |
| 180 | ``-DCMAKE_C_COMPILER=/path/to/clang -DCMAKE_CXX_COMPILER=/path/to/clang++``. |
| 181 | You can also use ``ccmake``, which provides a curses interface to configure |
| 182 | CMake variables in an interactive manner. |
| 183 | |
| 184 | As a result, the new ``compile_commands.json`` file should appear in the |
| 185 | current directory. You should link it to the LLVM source tree so that |
| 186 | Clang Tooling is able to use it: |
| 187 | |
| 188 | .. code-block:: console |
| 189 | |
| 190 | $ ln -s $PWD/compile_commands.json path/to/llvm/source/ |
| 191 | |
| 192 | Now you are ready to build and test LLVM using Ninja: |
| 193 | |
| 194 | .. code-block:: console |
| 195 | |
| 196 | $ ninja check-all |
| 197 | |
| 198 | Other target names can be used in the same way as with make. |
| 199 | |