Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / clang / 398b8e86ab421592f9e72b92c4558ea865b26e86 / . / docs / LibTooling.html
blob: 163d24a7f1a13a537cdee9a16ef8cb208c845097 [file] [log] [blame]
Manuel Klimekd80d4842012-04-25 14:20:13 +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>LibTooling</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>
Manuel Klimekb7ac6582012-05-24 17:16:23 +0000[diff] [blame]10
11<!--#include virtual="../menu.html.incl"-->
12
Manuel Klimekd80d4842012-04-25 14:20:13 +0000[diff] [blame]13<div id="content">
14
15<h1>LibTooling</h1>
16<p>LibTooling is a library to support writing standalone tools based on
17Clang. This document will provide a basic walkthrough of how to write
18a tool using LibTooling.</p>
Alexander Kornienko10509662012-09-19 15:17:49 +0000[diff] [blame]19<p>For the information on how to setup Clang Tooling for LLVM see
20<a href="HowToSetupToolingForLLVM.html">HowToSetupToolingForLLVM.html</a></p>
Manuel Klimekd80d4842012-04-25 14:20:13 +0000[diff] [blame]21
22<!-- ======================================================================= -->
23<h2 id="intro">Introduction</h2>
24<!-- ======================================================================= -->
25
Alexander Kornienko6fbe9822012-08-24 00:39:14 +0000[diff] [blame]26<p>Tools built with LibTooling, like Clang Plugins, run
27<code>FrontendActions</code> over code.
28<!-- See FIXME for a tutorial on how to write FrontendActions. -->
Manuel Klimekd80d4842012-04-25 14:20:13 +0000[diff] [blame]29In this tutorial, we'll demonstrate the different ways of running clang's
Alexander Kornienko6fbe9822012-08-24 00:39:14 +0000[diff] [blame]30<code>SyntaxOnlyAction</code>, which runs a quick syntax check, over a bunch of
Manuel Klimekd80d4842012-04-25 14:20:13 +0000[diff] [blame]31code.</p>
32
33<!-- ======================================================================= -->
34<h2 id="runoncode">Parsing a code snippet in memory.</h2>
35<!-- ======================================================================= -->
36
Alexander Kornienko6fbe9822012-08-24 00:39:14 +0000[diff] [blame]37<p>If you ever wanted to run a <code>FrontendAction</code> over some sample
38code, for example to unit test parts of the Clang AST,
39<code>runToolOnCode</code> is what you looked for. Let me give you an example:
Manuel Klimekd80d4842012-04-25 14:20:13 +0000[diff] [blame]40<pre>
41 #include "clang/Tooling/Tooling.h"
42
43 TEST(runToolOnCode, CanSyntaxCheckCode) {
44 // runToolOnCode returns whether the action was correctly run over the
45 // given code.
46 EXPECT_TRUE(runToolOnCode(new clang::SyntaxOnlyAction, "class X {};"));
47 }
48</pre>
49
50<!-- ======================================================================= -->
51<h2 id="standalonetool">Writing a standalone tool.</h2>
52<!-- ======================================================================= -->
53
Alexander Kornienko6fbe9822012-08-24 00:39:14 +0000[diff] [blame]54<p>Once you unit tested your <code>FrontendAction</code> to the point where it
55cannot possibly break, it's time to create a standalone tool. For a standalone
56tool to run clang, it first needs to figure out what command line arguments to
57use for a specified file. To that end we create a
58<code>CompilationDatabase</code>. There are different ways to create a
59compilation database, and we need to support all of them depending on
60command-line options. There's the <code>CommonOptionsParser</code> class
61that takes the responsibility to parse command-line parameters related to
62compilation databases and inputs, so that all tools share the implementation.
63</p>
Manuel Klimekd80d4842012-04-25 14:20:13 +0000[diff] [blame]64
Alexander Kornienko6fbe9822012-08-24 00:39:14 +0000[diff] [blame]65<h3 id="parsingcommonoptions">Parsing common tools options.</h3>
66<p><code>CompilationDatabase</code> can be read from a build directory or the
67command line. Using <code>CommonOptionsParser</code> allows for explicit
68specification of a compile command line, specification of build path using the
69<code>-p</code> command-line option, and automatic location of the compilation
70database using source files paths.
Manuel Klimekd80d4842012-04-25 14:20:13 +0000[diff] [blame]71<pre>
Alexander Kornienko6fbe9822012-08-24 00:39:14 +0000[diff] [blame]72#include "clang/Tooling/CommonOptionsParser.h"
73
74using namespace clang::tooling;
75
Manuel Klimekd80d4842012-04-25 14:20:13 +0000[diff] [blame]76int main(int argc, const char **argv) {
Alexander Kornienko6fbe9822012-08-24 00:39:14 +0000[diff] [blame]77 // CommonOptionsParser constructor will parse arguments and create a
78 // CompilationDatabase. In case of error it will terminate the program.
79 CommonOptionsParser OptionsParser(argc, argv);
Manuel Klimekd80d4842012-04-25 14:20:13 +0000[diff] [blame]80
Alexander Kornienko6fbe9822012-08-24 00:39:14 +0000[diff] [blame]81 // Use OptionsParser.GetCompilations() and OptionsParser.GetSourcePathList()
82 // to retrieve CompilationDatabase and the list of input file paths.
Manuel Klimekd80d4842012-04-25 14:20:13 +0000[diff] [blame]83}
84</pre>
85</p>
86
87<h3 id="tool">Creating and running a ClangTool.</h3>
Alexander Kornienko6fbe9822012-08-24 00:39:14 +0000[diff] [blame]88<p>Once we have a <code>CompilationDatabase</code>, we can create a
89<code>ClangTool</code> and run our <code>FrontendAction</code> over some code.
90For example, to run the <code>SyntaxOnlyAction</code> over the files "a.cc" and
91"b.cc" one would write:
Manuel Klimekd80d4842012-04-25 14:20:13 +0000[diff] [blame]92<pre>
93 // A clang tool can run over a number of sources in the same process...
94 std::vector&lt;std::string> Sources;
95 Sources.push_back("a.cc");
96 Sources.push_back("b.cc");
97
98 // We hand the CompilationDatabase we created and the sources to run over into
99 // the tool constructor.
Alexander Kornienko6fbe9822012-08-24 00:39:14 +0000[diff] [blame]100 ClangTool Tool(OptionsParser.GetCompilations(), Sources);
Manuel Klimekd80d4842012-04-25 14:20:13 +0000[diff] [blame]101
102 // The ClangTool needs a new FrontendAction for each translation unit we run
103 // on. Thus, it takes a FrontendActionFactory as parameter. To create a
104 // FrontendActionFactory from a given FrontendAction type, we call
105 // newFrontendActionFactory&lt;clang::SyntaxOnlyAction>().
106 int result = Tool.run(newFrontendActionFactory&lt;clang::SyntaxOnlyAction>());
107</pre>
108</p>
109
110<h3 id="main">Putting it together - the first tool.</h3>
111<p>Now we combine the two previous steps into our first real tool. This example
112tool is also checked into the clang tree at tools/clang-check/ClangCheck.cpp.
113<pre>
Alexander Kornienko6fbe9822012-08-24 00:39:14 +0000[diff] [blame]114// Declares clang::SyntaxOnlyAction.
Manuel Klimek59d7cc92012-07-12 18:32:50 +0000[diff] [blame]115#include "clang/Frontend/FrontendActions.h"
Alexander Kornienko6fbe9822012-08-24 00:39:14 +0000[diff] [blame]116#include "clang/Tooling/CommonOptionsParser.h"
Alexander Kornienko10509662012-09-19 15:17:49 +0000[diff] [blame]117#include "clang/Tooling/Tooling.h"
Alexander Kornienko6fbe9822012-08-24 00:39:14 +0000[diff] [blame]118// Declares llvm::cl::extrahelp.
119#include "llvm/Support/CommandLine.h"
Manuel Klimekd80d4842012-04-25 14:20:13 +0000[diff] [blame]120
Manuel Klimek59d7cc92012-07-12 18:32:50 +0000[diff] [blame]121using namespace clang::tooling;
122using namespace llvm;
Manuel Klimekd80d4842012-04-25 14:20:13 +0000[diff] [blame]123
Alexander Kornienko6fbe9822012-08-24 00:39:14 +0000[diff] [blame]124// CommonOptionsParser declares HelpMessage with a description of the common
125// command-line options related to the compilation database and input files.
126// It's nice to have this help message in all tools.
127static cl::extrahelp CommonHelp(CommonOptionsParser::HelpMessage);
Manuel Klimekd80d4842012-04-25 14:20:13 +0000[diff] [blame]128
Alexander Kornienko6fbe9822012-08-24 00:39:14 +0000[diff] [blame]129// A help message for this specific tool can be added afterwards.
130static cl::extrahelp MoreHelp("\nMore help text...");
Manuel Klimekd80d4842012-04-25 14:20:13 +0000[diff] [blame]131
Manuel Klimek59d7cc92012-07-12 18:32:50 +0000[diff] [blame]132int main(int argc, const char **argv) {
Alexander Kornienko6fbe9822012-08-24 00:39:14 +0000[diff] [blame]133 CommonOptionsParser OptionsParser(argc, argv);
134 ClangTool Tool(OptionsParser.GetCompilations(),
135 OptionsParser.GetSourcePathList());
136 return Tool.run(newFrontendActionFactory&lt;clang::SyntaxOnlyAction&gt;());
Manuel Klimek59d7cc92012-07-12 18:32:50 +0000[diff] [blame]137}
Manuel Klimekd80d4842012-04-25 14:20:13 +0000[diff] [blame]138</pre>
139</p>
140
141<h3 id="running">Running the tool on some code.</h3>
142<p>When you check out and build clang, clang-check is already built and
143available to you in bin/clang-check inside your build directory.</p>
144<p>You can run clang-check on a file in the llvm repository by specifying
145all the needed parameters after a "--" separator:
146<pre>
147 $ cd /path/to/source/llvm
148 $ export BD=/path/to/build/llvm
Manuel Klimek59d7cc92012-07-12 18:32:50 +0000[diff] [blame]149 $ $BD/bin/clang-check tools/clang/tools/clang-check/ClangCheck.cpp -- \
Manuel Klimekd80d4842012-04-25 14:20:13 +0000[diff] [blame]150 clang++ -D__STDC_CONSTANT_MACROS -D__STDC_LIMIT_MACROS \
151 -Itools/clang/include -I$BD/include -Iinclude -Itools/clang/lib/Headers -c
152</pre>
153</p>
154
155<p>As an alternative, you can also configure cmake to output a compile command
156database into its build directory:
157<pre>
158 # Alternatively to calling cmake, use ccmake, toggle to advanced mode and
159 # set the parameter CMAKE_EXPORT_COMPILE_COMMANDS from the UI.
160 $ cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON .
161</pre>
162</p>
163<p>
164This creates a file called compile_commands.json in the build directory. Now
165you can run clang-check over files in the project by specifying the build path
166as first argument and some source files as further positional arguments:
167<pre>
168 $ cd /path/to/source/llvm
169 $ export BD=/path/to/build/llvm
Manuel Klimek59d7cc92012-07-12 18:32:50 +0000[diff] [blame]170 $ $BD/bin/clang-check -p $BD tools/clang/tools/clang-check/ClangCheck.cpp
Manuel Klimekd80d4842012-04-25 14:20:13 +0000[diff] [blame]171</pre>
172</p>
173
Manuel Klimek59d7cc92012-07-12 18:32:50 +0000[diff] [blame]174<h3 id="builtin">Builtin includes.</h3>
175<p>Clang tools need their builtin headers and search for them the same way clang
176does. Thus, the default location to look for builtin headers is in a path
177$(dirname /path/to/tool)/../lib/clang/3.2/include relative to the tool
178binary. This works out-of-the-box for tools running from llvm's toplevel
179binary directory after building clang-headers, or if the tool is running
180from the binary directory of a clang install next to the clang binary.</p>
181
182<p>Tips: if your tool fails to find stddef.h or similar headers, call
183the tool with -v and look at the search paths it looks through.</p>
184
Manuel Klimek1e282e92012-06-06 17:51:31 +0000[diff] [blame]185<h3 id="linking">Linking.</h3>
186<p>Please note that this presents the linking requirements at the time of this
187writing. For the most up-to-date information, look at one of the tools'
188Makefiles (for example
189<a href="http://llvm.org/viewvc/llvm-project/cfe/trunk/tools/clang-check/Makefile?view=markup">clang-check/Makefile</a>).
190</p>
191
192<p>To link a binary using the tooling infrastructure, link in the following
193libraries:
194<ul>
Manuel Klimekf38d9322012-06-06 21:30:34 +0000[diff] [blame]195<li>Tooling</li>
Manuel Klimek1e282e92012-06-06 17:51:31 +0000[diff] [blame]196<li>Frontend</li>
Manuel Klimekf38d9322012-06-06 21:30:34 +0000[diff] [blame]197<li>Driver</li>
198<li>Serialization</li>
Manuel Klimek1e282e92012-06-06 17:51:31 +0000[diff] [blame]199<li>Parse</li>
200<li>Sema</li>
Manuel Klimekf38d9322012-06-06 21:30:34 +0000[diff] [blame]201<li>Analysis</li>
202<li>Edit</li>
203<li>AST</li>
204<li>Lex</li>
205<li>Basic</li>
Manuel Klimek1e282e92012-06-06 17:51:31 +0000[diff] [blame]206</ul>
207</p>
208
Manuel Klimekd80d4842012-04-25 14:20:13 +0000[diff] [blame]209</div>
210</body>
211</html>
212