Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / clang / 59d7cc9e4c376c12d4fa2c30337761dbec94e92d / . / docs / LibTooling.html
blob: 560d11548927df67a6037e5e9a02b84147ab39e2 [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>
19
20<!-- ======================================================================= -->
21<h2 id="intro">Introduction</h2>
22<!-- ======================================================================= -->
23
24<p>Tools built with LibTooling, like Clang Plugins, run FrontendActions over
25code. <!-- See FIXME for a tutorial on how to write FrontendActions. -->
26In this tutorial, we'll demonstrate the different ways of running clang's
27SyntaxOnlyAction, which runs a quick syntax check, over a bunch of
28code.</p>
29
30<!-- ======================================================================= -->
31<h2 id="runoncode">Parsing a code snippet in memory.</h2>
32<!-- ======================================================================= -->
33
34<p>If you ever wanted to run a FrontendAction over some sample code, for example
35to unit test parts of the Clang AST, runToolOnCode is what you looked for. Let
36me give you an example:
37<pre>
38 #include "clang/Tooling/Tooling.h"
39
40 TEST(runToolOnCode, CanSyntaxCheckCode) {
41 // runToolOnCode returns whether the action was correctly run over the
42 // given code.
43 EXPECT_TRUE(runToolOnCode(new clang::SyntaxOnlyAction, "class X {};"));
44 }
45</pre>
46
47<!-- ======================================================================= -->
48<h2 id="standalonetool">Writing a standalone tool.</h2>
49<!-- ======================================================================= -->
50
51<p>Once you unit tested your FrontendAction to the point where it cannot
52possibly break, it's time to create a standalone tool. For a standalone tool
53to run clang, it first needs to figure out what command line arguments to use
54for a specified file. To that end we create a CompilationDatabase.</p>
55
56<h3 id="compilationdb">Creating a compilation database.</h3>
57<p>CompilationDatabase provides static factory functions to help with parsing
58compile commands from a build directory or the command line. The following code
59allows for both explicit specification of a compile command line, as well as
60retrieving the compile commands lines from a database.
61<pre>
62int main(int argc, const char **argv) {
63 // First, try to create a fixed compile command database from the command line
64 // arguments.
65 llvm::OwningPtr&lt;CompilationDatabase> Compilations(
66 FixedCompilationDatabase::loadFromCommandLine(argc, argv));
67
68 // Next, use normal llvm command line parsing to get the tool specific
69 // parameters.
70 cl::ParseCommandLineOptions(argc, argv);
71
72 if (!Compilations) {
73 // In case the user did not specify the compile command line via positional
74 // command line arguments after "--", try to load the compile commands from
Manuel Klimek59d7cc92012-07-12 18:32:50 +0000[diff] [blame^]75 // a database in the specified build directory or auto-detect it from a
76 // source file.
Manuel Klimekd80d4842012-04-25 14:20:13 +0000[diff] [blame]77 std::string ErrorMessage;
Manuel Klimek59d7cc92012-07-12 18:32:50 +0000[diff] [blame^]78 if (!BuildPath.empty()) {
79 Compilations.reset(
80 CompilationDatabase::autoDetectFromDirectory(BuildPath, ErrorMessage));
81 } else {
82 Compilations.reset(CompilationDatabase::autoDetectFromSource(
83 SourcePaths[0], ErrorMessage));
84 }
Manuel Klimekd80d4842012-04-25 14:20:13 +0000[diff] [blame]85 // If there is still no valid compile command database, we don't know how
86 // to run the tool.
87 if (!Compilations)
88 llvm::report_fatal_error(ErrorMessage);
89 }
Manuel Klimekd80d4842012-04-25 14:20:13 +0000[diff] [blame]90}
91</pre>
92</p>
93
94<h3 id="tool">Creating and running a ClangTool.</h3>
95<p>Once we have a CompilationDatabase, we can create a ClangTool and run our
96FrontendAction over some code. For example, to run the SyntaxOnlyAction over
97the files "a.cc" and "b.cc" one would write:
98<pre>
99 // A clang tool can run over a number of sources in the same process...
100 std::vector&lt;std::string> Sources;
101 Sources.push_back("a.cc");
102 Sources.push_back("b.cc");
103
104 // We hand the CompilationDatabase we created and the sources to run over into
105 // the tool constructor.
106 ClangTool Tool(*Compilations, Sources);
107
108 // The ClangTool needs a new FrontendAction for each translation unit we run
109 // on. Thus, it takes a FrontendActionFactory as parameter. To create a
110 // FrontendActionFactory from a given FrontendAction type, we call
111 // newFrontendActionFactory&lt;clang::SyntaxOnlyAction>().
112 int result = Tool.run(newFrontendActionFactory&lt;clang::SyntaxOnlyAction>());
113</pre>
114</p>
115
116<h3 id="main">Putting it together - the first tool.</h3>
117<p>Now we combine the two previous steps into our first real tool. This example
118tool is also checked into the clang tree at tools/clang-check/ClangCheck.cpp.
119<pre>
Manuel Klimek59d7cc92012-07-12 18:32:50 +0000[diff] [blame^]120#include "llvm/Support/CommandLine.h"
121#include "clang/Frontend/FrontendActions.h"
122#include "clang/Tooling/CompilationDatabase.h"
123#include "clang/Tooling/Tooling.h"
Manuel Klimekd80d4842012-04-25 14:20:13 +0000[diff] [blame]124
Manuel Klimek59d7cc92012-07-12 18:32:50 +0000[diff] [blame^]125using namespace clang::tooling;
126using namespace llvm;
Manuel Klimekd80d4842012-04-25 14:20:13 +0000[diff] [blame]127
Manuel Klimek59d7cc92012-07-12 18:32:50 +0000[diff] [blame^]128cl::opt&lt;std::string> BuildPath(
129 "p",
130 cl::desc("&lt;build-path>"),
131 cl::Optional);
Manuel Klimekd80d4842012-04-25 14:20:13 +0000[diff] [blame]132
Manuel Klimek59d7cc92012-07-12 18:32:50 +0000[diff] [blame^]133cl::list&lt;std::string> SourcePaths(
134 cl::Positional,
135 cl::desc("&lt;source0> [... &lt;sourceN>]"),
136 cl::OneOrMore);
Manuel Klimekd80d4842012-04-25 14:20:13 +0000[diff] [blame]137
Manuel Klimek59d7cc92012-07-12 18:32:50 +0000[diff] [blame^]138int main(int argc, const char **argv) {
139 llvm::OwningPtr&lt;CompilationDatabase> Compilations(
140 FixedCompilationDatabase::loadFromCommandLine(argc, argv));
141 cl::ParseCommandLineOptions(argc, argv);
142 if (!Compilations) {
143 std::string ErrorMessage;
144 if (!BuildPath.empty()) {
145 Compilations.reset(
146 CompilationDatabase::autoDetectFromDirectory(BuildPath, ErrorMessage));
147 } else {
148 Compilations.reset(CompilationDatabase::autoDetectFromSource(
149 SourcePaths[0], ErrorMessage));
Manuel Klimekd80d4842012-04-25 14:20:13 +0000[diff] [blame]150 }
Manuel Klimek59d7cc92012-07-12 18:32:50 +0000[diff] [blame^]151 if (!Compilations)
152 llvm::report_fatal_error(ErrorMessage);
Manuel Klimekd80d4842012-04-25 14:20:13 +0000[diff] [blame]153 }
Manuel Klimek59d7cc92012-07-12 18:32:50 +0000[diff] [blame^]154 ClangTool Tool(*Compilations, SourcePaths);
155 return Tool.run(newFrontendActionFactory&lt;clang::SyntaxOnlyAction>());
156}
Manuel Klimekd80d4842012-04-25 14:20:13 +0000[diff] [blame]157</pre>
158</p>
159
160<h3 id="running">Running the tool on some code.</h3>
161<p>When you check out and build clang, clang-check is already built and
162available to you in bin/clang-check inside your build directory.</p>
163<p>You can run clang-check on a file in the llvm repository by specifying
164all the needed parameters after a "--" separator:
165<pre>
166 $ cd /path/to/source/llvm
167 $ export BD=/path/to/build/llvm
Manuel Klimek59d7cc92012-07-12 18:32:50 +0000[diff] [blame^]168 $ $BD/bin/clang-check tools/clang/tools/clang-check/ClangCheck.cpp -- \
Manuel Klimekd80d4842012-04-25 14:20:13 +0000[diff] [blame]169 clang++ -D__STDC_CONSTANT_MACROS -D__STDC_LIMIT_MACROS \
170 -Itools/clang/include -I$BD/include -Iinclude -Itools/clang/lib/Headers -c
171</pre>
172</p>
173
174<p>As an alternative, you can also configure cmake to output a compile command
175database into its build directory:
176<pre>
177 # Alternatively to calling cmake, use ccmake, toggle to advanced mode and
178 # set the parameter CMAKE_EXPORT_COMPILE_COMMANDS from the UI.
179 $ cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON .
180</pre>
181</p>
182<p>
183This creates a file called compile_commands.json in the build directory. Now
184you can run clang-check over files in the project by specifying the build path
185as first argument and some source files as further positional arguments:
186<pre>
187 $ cd /path/to/source/llvm
188 $ export BD=/path/to/build/llvm
Manuel Klimek59d7cc92012-07-12 18:32:50 +0000[diff] [blame^]189 $ $BD/bin/clang-check -p $BD tools/clang/tools/clang-check/ClangCheck.cpp
Manuel Klimekd80d4842012-04-25 14:20:13 +0000[diff] [blame]190</pre>
191</p>
192
Manuel Klimek59d7cc92012-07-12 18:32:50 +0000[diff] [blame^]193<h3 id="builtin">Builtin includes.</h3>
194<p>Clang tools need their builtin headers and search for them the same way clang
195does. Thus, the default location to look for builtin headers is in a path
196$(dirname /path/to/tool)/../lib/clang/3.2/include relative to the tool
197binary. This works out-of-the-box for tools running from llvm's toplevel
198binary directory after building clang-headers, or if the tool is running
199from the binary directory of a clang install next to the clang binary.</p>
200
201<p>Tips: if your tool fails to find stddef.h or similar headers, call
202the tool with -v and look at the search paths it looks through.</p>
203
Manuel Klimek1e282e92012-06-06 17:51:31 +0000[diff] [blame]204<h3 id="linking">Linking.</h3>
205<p>Please note that this presents the linking requirements at the time of this
206writing. For the most up-to-date information, look at one of the tools'
207Makefiles (for example
208<a href="http://llvm.org/viewvc/llvm-project/cfe/trunk/tools/clang-check/Makefile?view=markup">clang-check/Makefile</a>).
209</p>
210
211<p>To link a binary using the tooling infrastructure, link in the following
212libraries:
213<ul>
Manuel Klimekf38d9322012-06-06 21:30:34 +0000[diff] [blame]214<li>Tooling</li>
Manuel Klimek1e282e92012-06-06 17:51:31 +0000[diff] [blame]215<li>Frontend</li>
Manuel Klimekf38d9322012-06-06 21:30:34 +0000[diff] [blame]216<li>Driver</li>
217<li>Serialization</li>
Manuel Klimek1e282e92012-06-06 17:51:31 +0000[diff] [blame]218<li>Parse</li>
219<li>Sema</li>
Manuel Klimekf38d9322012-06-06 21:30:34 +0000[diff] [blame]220<li>Analysis</li>
221<li>Edit</li>
222<li>AST</li>
223<li>Lex</li>
224<li>Basic</li>
Manuel Klimek1e282e92012-06-06 17:51:31 +0000[diff] [blame]225</ul>
226</p>
227
Manuel Klimekd80d4842012-04-25 14:20:13 +0000[diff] [blame]228</div>
229</body>
230</html>
231