docs/LibTooling.html - platform/external/clang - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
           "http://www.w3.org/TR/html4/strict.dtd">
 <html>
 <head>
 <title>LibTooling</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>LibTooling</h1>
 <p>LibTooling is a library to support writing standalone tools based on
 Clang. This document will provide a basic walkthrough of how to write
 a tool using LibTooling.</p>

 <!-- ======================================================================= -->
 <h2 id="intro">Introduction</h2>
 <!-- ======================================================================= -->

 <p>Tools built with LibTooling, like Clang Plugins, run
 <code>FrontendActions</code> over code.
 <!-- See FIXME for a tutorial on how to write FrontendActions. -->
 In this tutorial, we'll demonstrate the different ways of running clang's
 <code>SyntaxOnlyAction</code>, which runs a quick syntax check, over a bunch of
 code.</p>

 <!-- ======================================================================= -->
 <h2 id="runoncode">Parsing a code snippet in memory.</h2>
 <!-- ======================================================================= -->

 <p>If you ever wanted to run a <code>FrontendAction</code> over some sample
 code, for example to unit test parts of the Clang AST,
 <code>runToolOnCode</code> is what you looked for. Let me give you an example:
 <pre>
   #include "clang/Tooling/Tooling.h"

   TEST(runToolOnCode, CanSyntaxCheckCode) {
     // runToolOnCode returns whether the action was correctly run over the
     // given code.
     EXPECT_TRUE(runToolOnCode(new clang::SyntaxOnlyAction, "class X {};"));
   }
 </pre>

 <!-- ======================================================================= -->
 <h2 id="standalonetool">Writing a standalone tool.</h2>
 <!-- ======================================================================= -->

 <p>Once you unit tested your <code>FrontendAction</code> to the point where it
 cannot possibly break, it's time to create a standalone tool. For a standalone
 tool to run clang, it first needs to figure out what command line arguments to
 use for a specified file. To that end we create a
 <code>CompilationDatabase</code>. There are different ways to create a
 compilation database, and we need to support all of them depending on
 command-line options. There's the <code>CommonOptionsParser</code> class
 that takes the responsibility to parse command-line parameters related to
 compilation databases and inputs, so that all tools share the implementation.
 </p>

 <h3 id="parsingcommonoptions">Parsing common tools options.</h3>
 <p><code>CompilationDatabase</code> can be read from a build directory or the
 command line. Using <code>CommonOptionsParser</code> allows for explicit
 specification of a compile command line, specification of build path using the
 <code>-p</code> command-line option, and automatic location of the compilation
 database using source files paths.
 <pre>
 #include "clang/Tooling/CommonOptionsParser.h"

 using namespace clang::tooling;

 int main(int argc, const char **argv) {
   // CommonOptionsParser constructor will parse arguments and create a
   // CompilationDatabase. In case of error it will terminate the program.
   CommonOptionsParser OptionsParser(argc, argv);

   // Use OptionsParser.GetCompilations() and OptionsParser.GetSourcePathList()
   // to retrieve CompilationDatabase and the list of input file paths.
 }
 </pre>
 </p>

 <h3 id="tool">Creating and running a ClangTool.</h3>
 <p>Once we have a <code>CompilationDatabase</code>, we can create a
 <code>ClangTool</code> and run our <code>FrontendAction</code> over some code.
 For example, to run the <code>SyntaxOnlyAction</code> over the files "a.cc" and
 "b.cc" one would write:
 <pre>
   // A clang tool can run over a number of sources in the same process...
   std::vector&lt;std::string> Sources;
   Sources.push_back("a.cc");
   Sources.push_back("b.cc");

   // We hand the CompilationDatabase we created and the sources to run over into
   // the tool constructor.
   ClangTool Tool(OptionsParser.GetCompilations(), Sources);

   // The ClangTool needs a new FrontendAction for each translation unit we run
   // on. Thus, it takes a FrontendActionFactory as parameter. To create a
   // FrontendActionFactory from a given FrontendAction type, we call
   // newFrontendActionFactory&lt;clang::SyntaxOnlyAction>().
   int result = Tool.run(newFrontendActionFactory&lt;clang::SyntaxOnlyAction>());
 </pre>
 </p>

 <h3 id="main">Putting it together - the first tool.</h3>
 <p>Now we combine the two previous steps into our first real tool. This example
 tool is also checked into the clang tree at tools/clang-check/ClangCheck.cpp.
 <pre>
 // Declares clang::SyntaxOnlyAction.
 #include "clang/Frontend/FrontendActions.h"
 #include "clang/Tooling/CommonOptionsParser.h"
 // Declares llvm::cl::extrahelp.
 #include "llvm/Support/CommandLine.h"

 using namespace clang::tooling;
 using namespace llvm;

 // CommonOptionsParser declares HelpMessage with a description of the common
 // command-line options related to the compilation database and input files.
 // It's nice to have this help message in all tools.
 static cl::extrahelp CommonHelp(CommonOptionsParser::HelpMessage);

 // A help message for this specific tool can be added afterwards.
 static cl::extrahelp MoreHelp("\nMore help text...");

 int main(int argc, const char **argv) {
   CommonOptionsParser OptionsParser(argc, argv);
   ClangTool Tool(OptionsParser.GetCompilations(),
                  OptionsParser.GetSourcePathList());
   return Tool.run(newFrontendActionFactory&lt;clang::SyntaxOnlyAction&gt;());
 }
 </pre>
 </p>

 <h3 id="running">Running the tool on some code.</h3>
 <p>When you check out and build clang, clang-check is already built and
 available to you in bin/clang-check inside your build directory.</p>
 <p>You can run clang-check on a file in the llvm repository by specifying
 all the needed parameters after a "--" separator:
 <pre>
   $ cd /path/to/source/llvm
   $ export BD=/path/to/build/llvm
   $ $BD/bin/clang-check tools/clang/tools/clang-check/ClangCheck.cpp -- \
     clang++ -D__STDC_CONSTANT_MACROS -D__STDC_LIMIT_MACROS \
     -Itools/clang/include -I$BD/include -Iinclude -Itools/clang/lib/Headers -c
 </pre>
 </p>

 <p>As an alternative, you can also configure cmake to output a compile command
 database into its build directory:
 <pre>
   # Alternatively to calling cmake, use ccmake, toggle to advanced mode and
   # set the parameter CMAKE_EXPORT_COMPILE_COMMANDS from the UI.
   $ cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON .
 </pre>
 </p>
 <p>
 This creates a file called compile_commands.json in the build directory. Now
 you can run clang-check over files in the project by specifying the build path
 as first argument and some source files as further positional arguments:
 <pre>
   $ cd /path/to/source/llvm
   $ export BD=/path/to/build/llvm
   $ $BD/bin/clang-check -p $BD tools/clang/tools/clang-check/ClangCheck.cpp
 </pre>
 </p>

 <h3 id="builtin">Builtin includes.</h3>
 <p>Clang tools need their builtin headers and search for them the same way clang
 does. Thus, the default location to look for builtin headers is in a path
 $(dirname /path/to/tool)/../lib/clang/3.2/include relative to the tool
 binary. This works out-of-the-box for tools running from llvm's toplevel
 binary directory after building clang-headers, or if the tool is running
 from the binary directory of a clang install next to the clang binary.</p>

 <p>Tips: if your tool fails to find stddef.h or similar headers, call
 the tool with -v and look at the search paths it looks through.</p>

 <h3 id="linking">Linking.</h3>
 <p>Please note that this presents the linking requirements at the time of this
 writing. For the most up-to-date information, look at one of the tools'
 Makefiles (for example
 <a href="http://llvm.org/viewvc/llvm-project/cfe/trunk/tools/clang-check/Makefile?view=markup">clang-check/Makefile</a>).
 </p>

 <p>To link a binary using the tooling infrastructure, link in the following
 libraries:
 <ul>
 <li>Tooling</li>
 <li>Frontend</li>
 <li>Driver</li>
 <li>Serialization</li>
 <li>Parse</li>
 <li>Sema</li>
 <li>Analysis</li>
 <li>Edit</li>
 <li>AST</li>
 <li>Lex</li>
 <li>Basic</li>
 </ul>
 </p>

 </div>
 </body>
 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
	"http://www.w3.org/TR/html4/strict.dtd">
	<html>
	<head>
	<title>LibTooling</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>LibTooling</h1>
	<p>LibTooling is a library to support writing standalone tools based on
	Clang. This document will provide a basic walkthrough of how to write
	a tool using LibTooling.</p>

	<!-- ======================================================================= -->
	<h2 id="intro">Introduction</h2>
	<!-- ======================================================================= -->

	<p>Tools built with LibTooling, like Clang Plugins, run
	<code>FrontendActions</code> over code.
	<!-- See FIXME for a tutorial on how to write FrontendActions. -->
	In this tutorial, we'll demonstrate the different ways of running clang's
	<code>SyntaxOnlyAction</code>, which runs a quick syntax check, over a bunch of
	code.</p>

	<!-- ======================================================================= -->
	<h2 id="runoncode">Parsing a code snippet in memory.</h2>
	<!-- ======================================================================= -->

	<p>If you ever wanted to run a <code>FrontendAction</code> over some sample
	code, for example to unit test parts of the Clang AST,
	<code>runToolOnCode</code> is what you looked for. Let me give you an example:
	<pre>
	#include "clang/Tooling/Tooling.h"

	TEST(runToolOnCode, CanSyntaxCheckCode) {
	// runToolOnCode returns whether the action was correctly run over the
	// given code.
	EXPECT_TRUE(runToolOnCode(new clang::SyntaxOnlyAction, "class X {};"));
	}
	</pre>

	<!-- ======================================================================= -->
	<h2 id="standalonetool">Writing a standalone tool.</h2>
	<!-- ======================================================================= -->

	<p>Once you unit tested your <code>FrontendAction</code> to the point where it
	cannot possibly break, it's time to create a standalone tool. For a standalone
	tool to run clang, it first needs to figure out what command line arguments to
	use for a specified file. To that end we create a
	<code>CompilationDatabase</code>. There are different ways to create a
	compilation database, and we need to support all of them depending on
	command-line options. There's the <code>CommonOptionsParser</code> class
	that takes the responsibility to parse command-line parameters related to
	compilation databases and inputs, so that all tools share the implementation.
	</p>

	<h3 id="parsingcommonoptions">Parsing common tools options.</h3>
	<p><code>CompilationDatabase</code> can be read from a build directory or the
	command line. Using <code>CommonOptionsParser</code> allows for explicit
	specification of a compile command line, specification of build path using the
	<code>-p</code> command-line option, and automatic location of the compilation
	database using source files paths.
	<pre>
	#include "clang/Tooling/CommonOptionsParser.h"

	using namespace clang::tooling;

	int main(int argc, const char **argv) {
	// CommonOptionsParser constructor will parse arguments and create a
	// CompilationDatabase. In case of error it will terminate the program.
	CommonOptionsParser OptionsParser(argc, argv);

	// Use OptionsParser.GetCompilations() and OptionsParser.GetSourcePathList()
	// to retrieve CompilationDatabase and the list of input file paths.
	}
	</pre>
	</p>

	<h3 id="tool">Creating and running a ClangTool.</h3>
	<p>Once we have a <code>CompilationDatabase</code>, we can create a
	<code>ClangTool</code> and run our <code>FrontendAction</code> over some code.
	For example, to run the <code>SyntaxOnlyAction</code> over the files "a.cc" and
	"b.cc" one would write:
	<pre>
	// A clang tool can run over a number of sources in the same process...
	std::vector<std::string> Sources;
	Sources.push_back("a.cc");
	Sources.push_back("b.cc");

	// We hand the CompilationDatabase we created and the sources to run over into
	// the tool constructor.
	ClangTool Tool(OptionsParser.GetCompilations(), Sources);

	// The ClangTool needs a new FrontendAction for each translation unit we run
	// on. Thus, it takes a FrontendActionFactory as parameter. To create a
	// FrontendActionFactory from a given FrontendAction type, we call
	// newFrontendActionFactory<clang::SyntaxOnlyAction>().
	int result = Tool.run(newFrontendActionFactory<clang::SyntaxOnlyAction>());
	</pre>
	</p>

	<h3 id="main">Putting it together - the first tool.</h3>
	<p>Now we combine the two previous steps into our first real tool. This example
	tool is also checked into the clang tree at tools/clang-check/ClangCheck.cpp.
	<pre>
	// Declares clang::SyntaxOnlyAction.
	#include "clang/Frontend/FrontendActions.h"
	#include "clang/Tooling/CommonOptionsParser.h"
	// Declares llvm::cl::extrahelp.
	#include "llvm/Support/CommandLine.h"

	using namespace clang::tooling;
	using namespace llvm;

	// CommonOptionsParser declares HelpMessage with a description of the common
	// command-line options related to the compilation database and input files.
	// It's nice to have this help message in all tools.
	static cl::extrahelp CommonHelp(CommonOptionsParser::HelpMessage);

	// A help message for this specific tool can be added afterwards.
	static cl::extrahelp MoreHelp("\nMore help text...");

	int main(int argc, const char **argv) {
	CommonOptionsParser OptionsParser(argc, argv);
	ClangTool Tool(OptionsParser.GetCompilations(),
	OptionsParser.GetSourcePathList());
	return Tool.run(newFrontendActionFactory<clang::SyntaxOnlyAction>());
	}
	</pre>
	</p>

	<h3 id="running">Running the tool on some code.</h3>
	<p>When you check out and build clang, clang-check is already built and
	available to you in bin/clang-check inside your build directory.</p>
	<p>You can run clang-check on a file in the llvm repository by specifying
	all the needed parameters after a "--" separator:
	<pre>
	$ cd /path/to/source/llvm
	$ export BD=/path/to/build/llvm
	$ $BD/bin/clang-check tools/clang/tools/clang-check/ClangCheck.cpp -- \
	clang++ -D__STDC_CONSTANT_MACROS -D__STDC_LIMIT_MACROS \
	-Itools/clang/include -I$BD/include -Iinclude -Itools/clang/lib/Headers -c
	</pre>
	</p>

	<p>As an alternative, you can also configure cmake to output a compile command
	database into its build directory:
	<pre>
	# Alternatively to calling cmake, use ccmake, toggle to advanced mode and
	# set the parameter CMAKE_EXPORT_COMPILE_COMMANDS from the UI.
	$ cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON .
	</pre>
	</p>
	<p>
	This creates a file called compile_commands.json in the build directory. Now
	you can run clang-check over files in the project by specifying the build path
	as first argument and some source files as further positional arguments:
	<pre>
	$ cd /path/to/source/llvm
	$ export BD=/path/to/build/llvm
	$ $BD/bin/clang-check -p $BD tools/clang/tools/clang-check/ClangCheck.cpp
	</pre>
	</p>

	<h3 id="builtin">Builtin includes.</h3>
	<p>Clang tools need their builtin headers and search for them the same way clang
	does. Thus, the default location to look for builtin headers is in a path
	$(dirname /path/to/tool)/../lib/clang/3.2/include relative to the tool
	binary. This works out-of-the-box for tools running from llvm's toplevel
	binary directory after building clang-headers, or if the tool is running
	from the binary directory of a clang install next to the clang binary.</p>

	<p>Tips: if your tool fails to find stddef.h or similar headers, call
	the tool with -v and look at the search paths it looks through.</p>

	<h3 id="linking">Linking.</h3>
	<p>Please note that this presents the linking requirements at the time of this
	writing. For the most up-to-date information, look at one of the tools'
	Makefiles (for example
	<a href="http://llvm.org/viewvc/llvm-project/cfe/trunk/tools/clang-check/Makefile?view=markup">clang-check/Makefile</a>).
	</p>

	<p>To link a binary using the tooling infrastructure, link in the following
	libraries:
	<ul>
	<li>Tooling</li>
	<li>Frontend</li>
	<li>Driver</li>
	<li>Serialization</li>
	<li>Parse</li>
	<li>Sema</li>
	<li>Analysis</li>
	<li>Edit</li>
	<li>AST</li>
	<li>Lex</li>
	<li>Basic</li>
	</ul>
	</p>

	</div>
	</body>
	</html>