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 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(nullptr /*Dump to stdout.*/,
 137                                         this->ASTDumpFilter);
 138       if (this->ASTPrint.operator _Bool())
 139           return clang::CreateASTPrinter(&llvm::outs(), this->ASTDumpFilter);
 140       return new clang::ASTConsumer();
 141   }
 142
 143 Using Ninja Build System
 144 =======================================
 145
 146 Optionally you can use the `Ninja <https://github.com/martine/ninja>`_
 147 build system instead of make. It is aimed at making your builds faster.
 148 Currently this step will require building Ninja from sources.
 149
 150 To take advantage of using Clang Tools along with Ninja build you need
 151 at least CMake 2.8.9.
 152
 153 Clone the Ninja git repository and build Ninja from sources:
 154
 155 .. code-block:: console
 156
 157   $ git clone git://github.com/martine/ninja.git
 158   $ cd ninja/
 159   $ ./bootstrap.py
 160
 161 This will result in a single binary ``ninja`` in the current directory.
 162 It doesn't require installation and can just be copied to any location
 163 inside ``$PATH``, say ``/usr/local/bin/``:
 164
 165 .. code-block:: console
 166
 167   $ sudo cp ninja /usr/local/bin/
 168   $ sudo chmod a+rx /usr/local/bin/ninja
 169
 170 After doing all of this, you'll need to generate Ninja build files for
 171 LLVM with CMake. You need to make a build directory and run CMake from
 172 it:
 173
 174 .. code-block:: console
 175
 176   $ mkdir your/build/directory
 177   $ cd your/build/directory
 178   $ cmake -G Ninja -DCMAKE_EXPORT_COMPILE_COMMANDS=ON path/to/llvm/sources
 179
 180 If you want to use clang instead of GCC, you can add
 181 ``-DCMAKE_C_COMPILER=/path/to/clang -DCMAKE_CXX_COMPILER=/path/to/clang++``.
 182 You can also use ``ccmake``, which provides a curses interface to configure
 183 CMake variables in an interactive manner.
 184
 185 As a result, the new ``compile_commands.json`` file should appear in the
 186 current directory. You should link it to the LLVM source tree so that
 187 Clang Tooling is able to use it:
 188
 189 .. code-block:: console
 190
 191   $ ln -s $PWD/compile_commands.json path/to/llvm/source/
 192
 193 Now you are ready to build and test LLVM using Ninja:
 194
 195 .. code-block:: console
 196
 197   $ ninja check-all
 198
 199 Other target names can be used in the same way as with make.