1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
|
<!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>
<p>For the information on how to setup Clang Tooling for LLVM see
<a href="HowToSetupToolingForLLVM.html">HowToSetupToolingForLLVM.html</a></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"
#include "clang/Tooling/Tooling.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>
|
