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