docs/HowToSetupToolingForLLVM.html - platform/external/clang - Gitiles

 <!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 &amp;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 &lt;silent&gt; &lt;F5&gt; :call ClangCheck()&lt;CR&gt;&lt;CR&gt;
 </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=&lt;string&gt;</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 &lt;/home/alexfh/local/llvm/tools/clang/tools/clang-check/ClangCheck.cpp:64:40, line:72:3&gt;
   (IfStmt 0x44d97c8 &lt;line:65:5, line:66:45&gt;
     &lt;&lt;&lt;NULL&gt;&gt;&gt;
       (ImplicitCastExpr 0x44d96d0 &lt;line:65:9&gt; '_Bool':'_Bool' &lt;UserDefinedConversion&gt;
 ...
 <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 &lt;anonymous namespace&gt;::ActionFactory::newASTConsumer:
 clang::ASTConsumer *newASTConsumer() {
     if (this-&gt;ASTList.operator _Bool())
         return clang::CreateASTDeclNodeLister();
     if (this-&gt;ASTDump.operator _Bool())
         return clang::CreateASTDumper(this-&gt;ASTDumpFilter);
     if (this-&gt;ASTPrint.operator _Bool())
         return clang::CreateASTPrinter(&amp;llvm::outs(), this-&gt;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>
	<!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>