Alexander Kornienko | a7f2c56 | 2012-07-11 14:27:44 +0000 | [diff] [blame] | 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" |
| 2 | "http://www.w3.org/TR/html4/strict.dtd"> |
| 3 | <html> |
| 4 | <head> |
| 5 | <title>How To Setup Clang Tooling For LLVM</title> |
| 6 | <link type="text/css" rel="stylesheet" href="../menu.css"> |
| 7 | <link type="text/css" rel="stylesheet" href="../content.css"> |
| 8 | </head> |
| 9 | <body> |
| 10 | |
| 11 | <!--#include virtual="../menu.html.incl"--> |
| 12 | |
| 13 | <div id="content"> |
| 14 | |
| 15 | <h1>How To Setup Clang Tooling For LLVM</h1> |
| 16 | <p>Clang Tooling provides infrastructure to write tools that need syntactic and |
| 17 | semantic infomation about a program. This term also relates to a set of specific |
| 18 | tools using this infrastructure (e.g. <code>clang-check</code>). This document |
| 19 | provides information on how to set up and use Clang Tooling for the LLVM source |
| 20 | code.</p> |
| 21 | |
| 22 | |
| 23 | <!-- ======================================================================= --> |
| 24 | <h2><a name="introduction">Introduction</a></h2> |
| 25 | <!-- ======================================================================= --> |
| 26 | |
| 27 | <p>Clang Tooling needs a compilation database to figure out specific build |
| 28 | options for each file. Currently it can create a compilation database from the |
| 29 | <code>compilation_commands.json</code> file, generated by CMake. When invoking |
| 30 | clang tools, you can either specify a path to a build directory using a command |
| 31 | line parameter <code>-p</code> or let Clang Tooling find this file in your |
| 32 | source tree. In either case you need to configure your build using CMake to use |
| 33 | clang tools.</p> |
| 34 | |
| 35 | <!-- ======================================================================= --> |
| 36 | <h2><a name="using-make">Setup Clang Tooling Using CMake and Make</a></h2> |
| 37 | <!-- ======================================================================= --> |
| 38 | |
| 39 | <p>If you intend to use make to build LLVM, you should have CMake 2.8.6 or later |
| 40 | installed (can be found <a href="http://cmake.org">here</a>).</p> |
| 41 | <p>First, you need to generate Makefiles for LLVM with CMake. You need to make |
| 42 | a build directory and run CMake from it:</p> |
| 43 | <pre> |
| 44 | mkdir your/build/directory |
| 45 | cd your/build/directory |
| 46 | cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON path/to/llvm/sources |
| 47 | </pre> |
| 48 | |
| 49 | <p>If you want to use clang instead of GCC, you can add |
| 50 | <code>-DCMAKE_C_COMPILER=/path/to/clang |
| 51 | -DCMAKE_CXX_COMPILER=/path/to/clang++</code>. |
| 52 | You can also use ccmake, which provides a curses interface to configure CMake |
| 53 | variables for lazy people.</p> |
| 54 | |
| 55 | <p>As a result, the new <code>compile_commands.json</code> file should appear in |
| 56 | the current directory. You should link it to the LLVM source tree so that Clang |
| 57 | Tooling is able to use it:</p> |
| 58 | <pre> |
| 59 | ln -s $PWD/compile_commands.json path/to/llvm/source/ |
| 60 | </pre> |
| 61 | |
| 62 | <p>Now you are ready to build and test LLVM using make:</p> |
| 63 | <pre> |
| 64 | make check-all |
| 65 | </pre> |
| 66 | |
| 67 | <!-- ======================================================================= --> |
| 68 | <h2><a name="using-tools">Using Clang Tools</a></h2> |
| 69 | <!-- ======================================================================= --> |
| 70 | |
| 71 | <p>After you completed the previous steps, you are ready to run clang tools. If |
| 72 | you have a recent clang installed, you should have <code>clang-check</code> in |
| 73 | $PATH. Try to run it on any .cpp file inside the LLVM source tree:</p> |
| 74 | <pre> |
| 75 | clang-check tools/clang/lib/Tooling/CompilationDatabase.cpp |
| 76 | </pre> |
| 77 | <p>If you're using vim, it's convenient to have clang-check integrated. Put this |
| 78 | into your .vimrc:</p> |
| 79 | <pre> |
| 80 | set makeprg=clang-check\ % |
| 81 | map <F5> :make<CR><CR> |
| 82 | </pre> |
| 83 | |
| 84 | <p>When editing C++ code, hit F5 to reparse the current buffer. The output will |
| 85 | go into the error window, which you can enable with <code>:cope</code>.</p> |
| 86 | |
| 87 | |
| 88 | <!-- ======================================================================= --> |
| 89 | <h2><a name="using-ninja">(Experimental) Using Ninja Build System</a></h2> |
| 90 | <!-- ======================================================================= --> |
| 91 | |
| 92 | <p>Optionally you can use the <a |
| 93 | href="https://github.com/martine/ninja">Ninja</a> build system instead of |
| 94 | make. It is aimed at making your builds faster. Currently this step will require |
| 95 | building Ninja from sources and using a development version of CMake.</p> |
| 96 | <p>To take advantage of using Clang Tools along with Ninja build you need at |
| 97 | least CMake 2.8.9. At the moment CMake 2.8.9 is still under development, so you |
| 98 | can get latest development sources and build it yourself:</p> |
| 99 | <pre> |
| 100 | git clone git://cmake.org/cmake.git |
| 101 | cd cmake |
| 102 | ./bootstrap |
| 103 | make |
| 104 | sudo make install |
| 105 | </pre> |
| 106 | |
| 107 | <p>Having the correct version of CMake, you can clone the Ninja git repository |
| 108 | and build Ninja from sources:</p> |
| 109 | <pre> |
| 110 | git clone git://github.com/martine/ninja.git |
| 111 | cd ninja/ |
| 112 | ./bootstrap.py |
| 113 | </pre> |
| 114 | <p>This will result in a single binary <code>ninja</code> in the current |
| 115 | directory. It doesn't require installation and can just be copied to any |
| 116 | location inside <code>$PATH</code>, say <code>/usr/local/bin/</code>:</p> |
| 117 | <pre> |
| 118 | sudo cp ninja /usr/local/bin/ |
| 119 | sudo chmod a+rx /usr/local/bin/ninja |
| 120 | </pre> |
| 121 | <p>After doing all of this, you'll need to generate Ninja build files for LLVM |
| 122 | with CMake. You need to make a build directory and run CMake from it:</p> |
| 123 | <pre> |
| 124 | mkdir your/build/directory |
| 125 | cd your/build/directory |
| 126 | cmake -G Ninja -DCMAKE_EXPORT_COMPILE_COMMANDS=ON path/to/llvm/sources |
| 127 | </pre> |
| 128 | |
| 129 | <p>If you want to use clang instead of GCC, you can add |
| 130 | <code>-DCMAKE_C_COMPILER=/path/to/clang |
| 131 | -DCMAKE_CXX_COMPILER=/path/to/clang++</code>. |
| 132 | You can also use ccmake, which provides a curses interface to configure CMake |
| 133 | variables in an interactive manner.</p> |
| 134 | |
| 135 | <p>As a result, the new <code>compile_commands.json</code> file should appear in |
| 136 | the current directory. You should link it to the LLVM source tree so that Clang |
| 137 | Tooling is able to use it:</p> |
| 138 | <pre> |
| 139 | ln -s $PWD/compile_commands.json path/to/llvm/source/ |
| 140 | </pre> |
| 141 | |
| 142 | <p>Now you are ready to build and test LLVM using Ninja:</p> |
| 143 | <pre> |
| 144 | ninja check-all |
| 145 | </pre> |
| 146 | <p>Other target names can be used in the same way as with make.</p> |
| 147 | </div> |
| 148 | </body> |
| 149 | </html> |
| 150 | |