clang/docs/HowToSetupToolingForLLVM.rst

   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 ``compile_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 <https://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.
  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 Setup Clang Tooling Using CMake on Windows
  57 ==========================================
  58
  59 For Windows developers, the Visual Studio project generators in CMake do
  60 not support `CMAKE_EXPORT_COMPILE_COMMANDS
  61 <https://cmake.org/cmake/help/latest/variable/CMAKE_EXPORT_COMPILE_COMMANDS.html>`_.
  62 However, the Ninja generator does support this variable and can be used
  63 on Windows to generate a suitable ``compile_commands.json`` that invokes
  64 the MSVC compiler.
  65
  66 First, you will need to install `Ninja`_.  Once installed, the Ninja
  67 executable will need to be in your search path for CMake to locate it.
  68
  69 Next, assuming you already have Visual Studio installed on your machine, you
  70 need to have the appropriate environment variables configured so that CMake
  71 will locate the MSVC compiler for the Ninja generator.  The `documentation
  72 <https://docs.microsoft.com/en-us/cpp/build/building-on-the-command-line?view=msvc-170#path_and_environment>`_
  73 describes the necessary environment variable settings, but the simplest thing
  74 is to use a `developer command-prompt window
  75 <https://docs.microsoft.com/en-us/cpp/build/building-on-the-command-line?view=msvc-170#developer_command_prompt_shortcuts>`_
  76 or call a `developer command file
  77 <https://docs.microsoft.com/en-us/cpp/build/building-on-the-command-line?view=msvc-170#developer_command_file_locations>`_
  78 to set the environment variables appropriately.
  79
  80 Now you can run CMake with the Ninja generator to export a compilation
  81 database:
  82
  83 .. code-block:: console
  84
  85   C:\> mkdir build-ninja
  86   C:\> cd build-ninja
  87   C:\build-ninja> cmake -G Ninja -DCMAKE_EXPORT_COMPILE_COMMANDS=ON path/to/llvm/sources
  88
  89 It is best to keep your Visual Studio IDE build folder separate from the
  90 Ninja build folder.  This prevents the two build systems from negatively
  91 interacting with each other.
  92
  93 Once the ``compile_commands.json`` file has been created by Ninja, you can
  94 use that compilation database with Clang Tooling.  One caveat is that because
  95 there are indirect settings obtained through the environment variables,
  96 you may need to run any Clang Tooling executables through a command prompt
  97 window created for use with Visual Studio as described above.  An
  98 alternative, e.g. for using the Visual Studio debugger on a Clang Tooling
  99 executable, is to ensure that the environment variables are also visible
 100 to the debugger settings.  This can be done locally in Visual Studio's
 101 debugger configuration locally or globally by launching the Visual Studio
 102 IDE from a suitable command-prompt window.
 103
 104 Using Clang Tools
 105 =================
 106
 107 After you completed the previous steps, you are ready to run clang tools. If
 108 you have a recent clang installed, you should have ``clang-check`` in
 109 ``$PATH``. Try to run it on any ``.cpp`` file inside the LLVM source tree:
 110
 111 .. code-block:: console
 112
 113   $ clang-check tools/clang/lib/Tooling/CompilationDatabase.cpp
 114
 115 If you're using vim, it's convenient to have clang-check integrated. Put
 116 this into your ``.vimrc``:
 117
 118 ::
 119
 120     function! ClangCheckImpl(cmd)
 121       if &autowrite | wall | endif
 122       echo "Running " . a:cmd . " ..."
 123       let l:output = system(a:cmd)
 124       cexpr l:output
 125       cwindow
 126       let w:quickfix_title = a:cmd
 127       if v:shell_error != 0
 128         cc
 129       endif
 130       let g:clang_check_last_cmd = a:cmd
 131     endfunction
 132
 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       else
 140         echo "Can't detect file's compilation arguments and no previous clang-check invocation!"
 141       endif
 142     endfunction
 143
 144     nmap <silent> <F5> :call ClangCheck()<CR><CR>
 145
 146 When editing a .cpp/.cxx/.cc/.c file, hit F5 to reparse the file. In
 147 case the current file has a different extension (for example, .h), F5
 148 will re-run the last clang-check invocation made from this vim instance
 149 (if any). The output will go into the error window, which is opened
 150 automatically when clang-check finds errors, and can be re-opened with
 151 ``:cope``.
 152
 153 Other ``clang-check`` options that can be useful when working with clang
 154 AST:
 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`` to
 159   dump/print only AST declaration nodes having a certain substring in a
 160   qualified name. Use ``-ast-list`` to list all filterable declaration node
 161   names.
 162 * ``-ast-list`` --- Build ASTs and print the list of declaration node qualified
 163   names.
 164
 165 Examples:
 166
 167 .. code-block:: console
 168
 169   $ clang-check tools/clang/tools/clang-check/ClangCheck.cpp -ast-dump -ast-dump-filter ActionFactory::newASTConsumer
 170   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::newASTConsumer
 178   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
 191 Using Ninja Build System
 192 =======================================
 193
 194 Optionally you can use the `Ninja`_ build system instead of make. It is
 195 aimed at making your builds faster.  Currently this step will require
 196 building Ninja from sources.
 197
 198 To take advantage of using Clang Tools along with Ninja build you need
 199 at least CMake 2.8.9.
 200
 201 Clone the Ninja git repository and build Ninja from sources:
 202
 203 .. code-block:: console
 204
 205   $ git clone git://github.com/martine/ninja.git
 206   $ cd ninja/
 207   $ ./bootstrap.py
 208
 209 This will result in a single binary ``ninja`` in the current directory.
 210 It doesn't require installation and can just be copied to any location
 211 inside ``$PATH``, say ``/usr/local/bin/``:
 212
 213 .. code-block:: console
 214
 215   $ sudo cp ninja /usr/local/bin/
 216   $ sudo chmod a+rx /usr/local/bin/ninja
 217
 218 After doing all of this, you'll need to generate Ninja build files for
 219 LLVM with CMake. You need to make a build directory and run CMake from
 220 it:
 221
 222 .. code-block:: console
 223
 224   $ mkdir your/build/directory
 225   $ cd your/build/directory
 226   $ cmake -G Ninja -DCMAKE_EXPORT_COMPILE_COMMANDS=ON path/to/llvm/sources
 227
 228 If you want to use clang instead of GCC, you can add
 229 ``-DCMAKE_C_COMPILER=/path/to/clang -DCMAKE_CXX_COMPILER=/path/to/clang++``.
 230 You can also use ``ccmake``, which provides a curses interface to configure
 231 CMake variables in an interactive manner.
 232
 233 As a result, the new ``compile_commands.json`` file should appear in the
 234 current directory. You should link it to the LLVM source tree so that
 235 Clang Tooling is able to use it:
 236
 237 .. code-block:: console
 238
 239   $ ln -s $PWD/compile_commands.json path/to/llvm/source/
 240
 241 Now you are ready to build and test LLVM using Ninja:
 242
 243 .. code-block:: console
 244
 245   $ ninja check-all
 246
 247 Other target names can be used in the same way as with make.
 248
 249 .. _Ninja: https://ninja-build.org/