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 ``compilation_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 <http://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(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 145Optionally you can use the `Ninja <https://github.com/martine/ninja>`_ 146build system instead of make. It is aimed at making your builds faster. 147Currently this step will require building Ninja from sources. 148 149To take advantage of using Clang Tools along with Ninja build you need 150at least CMake 2.8.9. 151 152Clone 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 160This will result in a single binary ``ninja`` in the current directory. 161It doesn't require installation and can just be copied to any location 162inside ``$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 169After doing all of this, you'll need to generate Ninja build files for 170LLVM with CMake. You need to make a build directory and run CMake from 171it: 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 179If you want to use clang instead of GCC, you can add 180``-DCMAKE_C_COMPILER=/path/to/clang -DCMAKE_CXX_COMPILER=/path/to/clang++``. 181You can also use ``ccmake``, which provides a curses interface to configure 182CMake variables in an interactive manner. 183 184As a result, the new ``compile_commands.json`` file should appear in the 185current directory. You should link it to the LLVM source tree so that 186Clang Tooling is able to use it: 187 188.. code-block:: console 189 190 $ ln -s $PWD/compile_commands.json path/to/llvm/source/ 191 192Now you are ready to build and test LLVM using Ninja: 193 194.. code-block:: console 195 196 $ ninja check-all 197 198Other target names can be used in the same way as with make. 199 200