diff options
Diffstat (limited to 'docs/HowToSetupToolingForLLVM.html')
| -rw-r--r-- | docs/HowToSetupToolingForLLVM.html | 186 |
1 files changed, 186 insertions, 0 deletions
diff --git a/docs/HowToSetupToolingForLLVM.html b/docs/HowToSetupToolingForLLVM.html new file mode 100644 index 0000000..493c882 --- /dev/null +++ b/docs/HowToSetupToolingForLLVM.html @@ -0,0 +1,186 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> +<html> +<head> +<title>How To Setup Clang Tooling For LLVM</title> +<link type="text/css" rel="stylesheet" href="../menu.css"> +<link type="text/css" rel="stylesheet" href="../content.css"> +</head> +<body> + +<!--#include virtual="../menu.html.incl"--> + +<div id="content"> + +<h1>How To Setup Clang Tooling For LLVM</h1> +<p>Clang Tooling provides infrastructure to write tools that need syntactic and +semantic infomation about a program. This term also relates to a set of specific +tools using this infrastructure (e.g. <code>clang-check</code>). This document +provides information on how to set up and use Clang Tooling for the LLVM source +code.</p> + + +<!-- ======================================================================= --> +<h2><a name="introduction">Introduction</a></h2> +<!-- ======================================================================= --> + +<p>Clang Tooling needs a compilation database to figure out specific build +options for each file. Currently it can create a compilation database from the +<code>compilation_commands.json</code> file, generated by CMake. When invoking +clang tools, you can either specify a path to a build directory using a command +line parameter <code>-p</code> or let Clang Tooling find this file in your +source tree. In either case you need to configure your build using CMake to use +clang tools.</p> + +<!-- ======================================================================= --> +<h2><a name="using-make">Setup Clang Tooling Using CMake and Make</a></h2> +<!-- ======================================================================= --> + +<p>If you intend to use make to build LLVM, you should have CMake 2.8.6 or later +installed (can be found <a href="http://cmake.org">here</a>).</p> +<p>First, you need to generate Makefiles for LLVM with CMake. You need to make +a build directory and run CMake from it:</p> +<pre> + mkdir your/build/directory + cd your/build/directory + cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON path/to/llvm/sources +</pre> + +<p>If you want to use clang instead of GCC, you can add +<code>-DCMAKE_C_COMPILER=/path/to/clang + -DCMAKE_CXX_COMPILER=/path/to/clang++</code>. +You can also use ccmake, which provides a curses interface to configure CMake +variables for lazy people.</p> + +<p>As a result, the new <code>compile_commands.json</code> file should appear in +the current directory. You should link it to the LLVM source tree so that Clang +Tooling is able to use it:</p> +<pre> + ln -s $PWD/compile_commands.json path/to/llvm/source/ +</pre> + +<p>Now you are ready to build and test LLVM using make:</p> +<pre> + make check-all +</pre> + +<!-- ======================================================================= --> +<h2><a name="using-tools">Using Clang Tools</a></h2> +<!-- ======================================================================= --> + +<p>After you completed the previous steps, you are ready to run clang tools. If +you have a recent clang installed, you should have <code>clang-check</code> in +$PATH. Try to run it on any .cpp file inside the LLVM source tree:</p> +<pre> + clang-check tools/clang/lib/Tooling/CompilationDatabase.cpp +</pre> +<p>If you're using vim, it's convenient to have clang-check integrated. Put this +into your .vimrc:</p> +<pre> + set makeprg=clang-check\ % + map <F5> :make<CR><CR> +</pre> + +<p>When editing C++ code, hit F5 to reparse the current buffer. The output will +go into the error window, which you can enable with <code>:cope</code>.</p> + +<p>Other <code>clang-check</code> options that can be useful when working with +clang AST:</p> +<ul> + <li><code>-ast-print</code> - Build ASTs and then pretty-print them.</li> + <li><code>-ast-dump</code> - Build ASTs and then debug dump them.</li> + <li><code>-ast-dump-filter=<string></code> - Use with + <code>-ast-dump</code> or <code>-ast-print</code> to dump/print + only AST declaration nodes having a certain substring in a qualified name. + Use <code>-ast-list</code> to list all filterable declaration node + names.</li> + <li><code>-ast-list</code> - Build ASTs and print the list of declaration + node qualified names.</li> +</ul> +<p>Examples:</p> +<pre> +<b>$ clang-check tools/clang/tools/clang-check/ClangCheck.cpp -ast-dump -ast-dump-filter ActionFactory::newASTConsumer</b> +Processing: tools/clang/tools/clang-check/ClangCheck.cpp. +Dumping <anonymous namespace>::ActionFactory::newASTConsumer: +clang::ASTConsumer *newASTConsumer() (CompoundStmt 0x44da290 </home/alexfh/local/llvm/tools/clang/tools/clang-check/ClangCheck.cpp:64:40, line:72:3> + (IfStmt 0x44d97c8 <line:65:5, line:66:45> + <<<NULL>>> + (ImplicitCastExpr 0x44d96d0 <line:65:9> '_Bool':'_Bool' <UserDefinedConversion> +... +<b>$ clang-check tools/clang/tools/clang-check/ClangCheck.cpp -ast-print -ast-dump-filter ActionFactory::newASTConsumer</b> +Processing: tools/clang/tools/clang-check/ClangCheck.cpp. +Printing <anonymous namespace>::ActionFactory::newASTConsumer: +clang::ASTConsumer *newASTConsumer() { + if (this->ASTList.operator _Bool()) + return clang::CreateASTDeclNodeLister(); + if (this->ASTDump.operator _Bool()) + return clang::CreateASTDumper(this->ASTDumpFilter); + if (this->ASTPrint.operator _Bool()) + return clang::CreateASTPrinter(&llvm::outs(), this->ASTDumpFilter); + return new clang::ASTConsumer(); +} +</pre> + +<!-- ======================================================================= --> +<h2><a name="using-ninja">(Experimental) Using Ninja Build System</a></h2> +<!-- ======================================================================= --> + +<p>Optionally you can use the <a + href="https://github.com/martine/ninja">Ninja</a> build system instead of +make. It is aimed at making your builds faster. Currently this step will require +building Ninja from sources and using a development version of CMake.</p> +<p>To take advantage of using Clang Tools along with Ninja build you need at +least CMake 2.8.9. At the moment CMake 2.8.9 is still under development, so you +can get latest development sources and build it yourself:</p> +<pre> + git clone git://cmake.org/cmake.git + cd cmake + ./bootstrap + make + sudo make install +</pre> + +<p>Having the correct version of CMake, you can clone the Ninja git repository +and build Ninja from sources:</p> +<pre> + git clone git://github.com/martine/ninja.git + cd ninja/ + ./bootstrap.py +</pre> +<p>This will result in a single binary <code>ninja</code> in the current +directory. It doesn't require installation and can just be copied to any +location inside <code>$PATH</code>, say <code>/usr/local/bin/</code>:</p> +<pre> + sudo cp ninja /usr/local/bin/ + sudo chmod a+rx /usr/local/bin/ninja +</pre> +<p>After doing all of this, you'll need to generate Ninja build files for LLVM +with CMake. You need to make a build directory and run CMake from it:</p> +<pre> + mkdir your/build/directory + cd your/build/directory + cmake -G Ninja -DCMAKE_EXPORT_COMPILE_COMMANDS=ON path/to/llvm/sources +</pre> + +<p>If you want to use clang instead of GCC, you can add +<code>-DCMAKE_C_COMPILER=/path/to/clang + -DCMAKE_CXX_COMPILER=/path/to/clang++</code>. +You can also use ccmake, which provides a curses interface to configure CMake +variables in an interactive manner.</p> + +<p>As a result, the new <code>compile_commands.json</code> file should appear in +the current directory. You should link it to the LLVM source tree so that Clang +Tooling is able to use it:</p> +<pre> + ln -s $PWD/compile_commands.json path/to/llvm/source/ +</pre> + +<p>Now you are ready to build and test LLVM using Ninja:</p> +<pre> + ninja check-all +</pre> +<p>Other target names can be used in the same way as with make.</p> +</div> +</body> +</html> + |
