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