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 ``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. 147 Currently this step will require building Ninja from sources. 148 149 To take advantage of using Clang Tools along with Ninja build you need 150 at least CMake 2.8.9. 151 152 Clone the Ninja git repository and build Ninja from sources: 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 200
