250 lines · plain
1===================================2How To Setup Clang Tooling For LLVM3===================================4 5Clang Tooling provides infrastructure to write tools that need syntactic6and semantic information about a program. This term also relates to a set7of specific tools using this infrastructure (e.g. ``clang-check``). This8document provides information on how to set up and use Clang Tooling for9the LLVM source code.10 11Introduction12============13 14Clang Tooling needs a compilation database to figure out specific build15options for each file. Currently it can create a compilation database16from the ``compile_commands.json`` file, generated by CMake. When17invoking clang tools, you can either specify a path to a build directory18using a command line parameter ``-p`` or let Clang Tooling find this19file in your source tree. In either case you need to configure your20build using CMake to use clang tools.21 22Setup Clang Tooling Using CMake and Make23========================================24 25If you intend to use make to build LLVM, you should have CMake 2.8.6 or26later installed (can be found `here <https://cmake.org>`_).27 28First, you need to generate Makefiles for LLVM with CMake. You need to29make a build directory and run CMake from it:30 31.. code-block:: console32 33 $ mkdir your/build/directory34 $ cd your/build/directory35 $ cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON path/to/llvm/sources36 37If you want to use clang instead of GCC, you can add38``-DCMAKE_C_COMPILER=/path/to/clang -DCMAKE_CXX_COMPILER=/path/to/clang++``.39You can also use ``ccmake``, which provides a curses interface to configure40CMake variables.41 42As a result, the new ``compile_commands.json`` file should appear in the43current directory. You should link it to the LLVM source tree so that44Clang Tooling is able to use it:45 46.. code-block:: console47 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:: console53 54 $ make check-all55 56Setup Clang Tooling Using CMake on Windows57==========================================58 59For Windows developers, the Visual Studio project generators in CMake do60not support `CMAKE_EXPORT_COMPILE_COMMANDS61<https://cmake.org/cmake/help/latest/variable/CMAKE_EXPORT_COMPILE_COMMANDS.html>`_.62However, the Ninja generator does support this variable and can be used63on Windows to generate a suitable ``compile_commands.json`` that invokes64the MSVC compiler.65 66First, you will need to install `Ninja`_. Once installed, the Ninja67executable will need to be in your search path for CMake to locate it.68 69Next, assuming you already have Visual Studio installed on your machine, you70need to have the appropriate environment variables configured so that CMake71will locate the MSVC compiler for the Ninja generator. The `documentation72<https://docs.microsoft.com/en-us/cpp/build/building-on-the-command-line?view=msvc-170#path_and_environment>`_73describes the necessary environment variable settings, but the simplest thing74is to use a `developer command-prompt window75<https://docs.microsoft.com/en-us/cpp/build/building-on-the-command-line?view=msvc-170#developer_command_prompt_shortcuts>`_76or call a `developer command file77<https://docs.microsoft.com/en-us/cpp/build/building-on-the-command-line?view=msvc-170#developer_command_file_locations>`_78to set the environment variables appropriately.79 80Now you can run CMake with the Ninja generator to export a compilation81database:82 83.. code-block:: console84 85 C:\> mkdir build-ninja86 C:\> cd build-ninja87 C:\build-ninja> cmake -G Ninja -DCMAKE_EXPORT_COMPILE_COMMANDS=ON path/to/llvm/sources88 89It is best to keep your Visual Studio IDE build folder separate from the90Ninja build folder. This prevents the two build systems from negatively91interacting with each other.92 93Once the ``compile_commands.json`` file has been created by Ninja, you can94use that compilation database with Clang Tooling. One caveat is that because95there are indirect settings obtained through the environment variables,96you may need to run any Clang Tooling executables through a command prompt97window created for use with Visual Studio as described above. An98alternative, e.g. for using the Visual Studio debugger on a Clang Tooling99executable, is to ensure that the environment variables are also visible100to the debugger settings. This can be done locally in Visual Studio's101debugger configuration locally or globally by launching the Visual Studio102IDE from a suitable command-prompt window.103 104Using Clang Tools105=================106 107After you completed the previous steps, you are ready to run clang tools. If108you have a recent clang installed, you should have ``clang-check`` in109``$PATH``. Try to run it on any ``.cpp`` file inside the LLVM source tree:110 111.. code-block:: console112 113 $ clang-check tools/clang/lib/Tooling/CompilationDatabase.cpp114 115If you're using vim, it's convenient to have clang-check integrated. Put116this into your ``.vimrc``:117 118::119 120 function! ClangCheckImpl(cmd)121 if &autowrite | wall | endif122 echo "Running " . a:cmd . " ..."123 let l:output = system(a:cmd)124 cexpr l:output125 cwindow126 let w:quickfix_title = a:cmd127 if v:shell_error != 0128 cc129 endif130 let g:clang_check_last_cmd = a:cmd131 endfunction132 133 function! ClangCheck()134 let l:filename = expand('%')135 if l:filename =~ '\.\(cpp\|cxx\|cc\|c\)$'136 call ClangCheckImpl("clang-check " . l:filename)137 elseif exists("g:clang_check_last_cmd")138 call ClangCheckImpl(g:clang_check_last_cmd)139 else140 echo "Can't detect file's compilation arguments and no previous clang-check invocation!"141 endif142 endfunction143 144 nmap <silent> <F5> :call ClangCheck()<CR><CR>145 146When editing a .cpp/.cxx/.cc/.c file, hit F5 to reparse the file. In147case the current file has a different extension (for example, .h), F5148will re-run the last clang-check invocation made from this vim instance149(if any). The output will go into the error window, which is opened150automatically when clang-check finds errors, and can be re-opened with151``:cope``.152 153Other ``clang-check`` options that can be useful when working with clang154AST:155 156* ``-ast-print`` --- Build ASTs and then pretty-print them.157* ``-ast-dump`` --- Build ASTs and then debug dump them.158* ``-ast-dump-filter=<string>`` --- Use with ``-ast-dump`` or ``-ast-print`` to159 dump/print only AST declaration nodes having a certain substring in a160 qualified name. Use ``-ast-list`` to list all filterable declaration node161 names.162* ``-ast-list`` --- Build ASTs and print the list of declaration node qualified163 names.164 165Examples:166 167.. code-block:: console168 169 $ clang-check tools/clang/tools/clang-check/ClangCheck.cpp -ast-dump -ast-dump-filter ActionFactory::newASTConsumer170 Processing: tools/clang/tools/clang-check/ClangCheck.cpp.171 Dumping ::ActionFactory::newASTConsumer:172 clang::ASTConsumer *newASTConsumer() (CompoundStmt 0x44da290 </home/alexfh/local/llvm/tools/clang/tools/clang-check/ClangCheck.cpp:64:40, line:72:3>173 (IfStmt 0x44d97c8 <line:65:5, line:66:45>174 <<<NULL>>>175 (ImplicitCastExpr 0x44d96d0 <line:65:9> '_Bool' <UserDefinedConversion>176 ...177 $ clang-check tools/clang/tools/clang-check/ClangCheck.cpp -ast-print -ast-dump-filter ActionFactory::newASTConsumer178 Processing: tools/clang/tools/clang-check/ClangCheck.cpp.179 Printing <anonymous namespace>::ActionFactory::newASTConsumer:180 clang::ASTConsumer *newASTConsumer() {181 if (this->ASTList.operator _Bool())182 return clang::CreateASTDeclNodeLister();183 if (this->ASTDump.operator _Bool())184 return clang::CreateASTDumper(nullptr /*Dump to stdout.*/,185 this->ASTDumpFilter);186 if (this->ASTPrint.operator _Bool())187 return clang::CreateASTPrinter(&llvm::outs(), this->ASTDumpFilter);188 return new clang::ASTConsumer();189 }190 191Using Ninja Build System192=======================================193 194Optionally you can use the `Ninja`_ build system instead of make. It is195aimed at making your builds faster. Currently this step will require196building Ninja from sources.197 198To take advantage of using Clang Tools along with Ninja build you need199at least CMake 2.8.9.200 201Clone the Ninja git repository and build Ninja from sources:202 203.. code-block:: console204 205 $ git clone git://github.com/martine/ninja.git206 $ cd ninja/207 $ ./bootstrap.py208 209This will result in a single binary ``ninja`` in the current directory.210It doesn't require installation and can just be copied to any location211inside ``$PATH``, say ``/usr/local/bin/``:212 213.. code-block:: console214 215 $ sudo cp ninja /usr/local/bin/216 $ sudo chmod a+rx /usr/local/bin/ninja217 218After doing all of this, you'll need to generate Ninja build files for219LLVM with CMake. You need to make a build directory and run CMake from220it:221 222.. code-block:: console223 224 $ mkdir your/build/directory225 $ cd your/build/directory226 $ cmake -G Ninja -DCMAKE_EXPORT_COMPILE_COMMANDS=ON path/to/llvm/sources227 228If you want to use clang instead of GCC, you can add229``-DCMAKE_C_COMPILER=/path/to/clang -DCMAKE_CXX_COMPILER=/path/to/clang++``.230You can also use ``ccmake``, which provides a curses interface to configure231CMake variables in an interactive manner.232 233As a result, the new ``compile_commands.json`` file should appear in the234current directory. You should link it to the LLVM source tree so that235Clang Tooling is able to use it:236 237.. code-block:: console238 239 $ ln -s $PWD/compile_commands.json path/to/llvm/source/240 241Now you are ready to build and test LLVM using Ninja:242 243.. code-block:: console244 245 $ ninja check-all246 247Other target names can be used in the same way as with make.248 249.. _Ninja: https://ninja-build.org/250