forked from OSchip/llvm-project
213 lines
8.5 KiB
HTML
213 lines
8.5 KiB
HTML
<!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>
|
|
function! ClangCheckImpl(cmd)
|
|
if &autowrite | wall | endif
|
|
echo "Running " . a:cmd . " ..."
|
|
let l:output = system(a:cmd)
|
|
cexpr l:output
|
|
cwindow
|
|
let w:quickfix_title = a:cmd
|
|
if v:shell_error != 0
|
|
cc
|
|
endif
|
|
let g:clang_check_last_cmd = a:cmd
|
|
endfunction
|
|
|
|
function! ClangCheck()
|
|
let l:filename = expand('%')
|
|
if l:filename =~ '\.\(cpp\|cxx\|cc\|c\)$'
|
|
call ClangCheckImpl("clang-check " . l:filename)
|
|
elseif exists("g:clang_check_last_cmd")
|
|
call ClangCheckImpl(g:clang_check_last_cmd)
|
|
else
|
|
echo "Can't detect file's compilation arguments and no previous clang-check invocation!"
|
|
endif
|
|
endfunction
|
|
|
|
nmap <silent> <F5> :call ClangCheck()<CR><CR>
|
|
</pre>
|
|
|
|
<p>When editing a .cpp/.cxx/.cc/.c file, hit F5 to reparse the file. In case
|
|
the current file has a different extension (for example, .h), F5 will re-run
|
|
the last clang-check invocation made from this vim instance (if any). The
|
|
output will go into the error window, which is opened automatically when
|
|
clang-check finds errors, and can be re-opened 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>
|
|
|