Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / clang / d80d484168c8b12f2c09fdecf43999478fcb4348 / . / docs / LibTooling.html
blob: 5be61fa50b519f9f38eab01e64d0407281a6ee30 [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>
10<div id="content">
11
12<h1>LibTooling</h1>
13<p>LibTooling is a library to support writing standalone tools based on
14Clang. This document will provide a basic walkthrough of how to write
15a tool using LibTooling.</p>
16
17<!-- ======================================================================= -->
18<h2 id="intro">Introduction</h2>
19<!-- ======================================================================= -->
20
21<p>Tools built with LibTooling, like Clang Plugins, run FrontendActions over
22code. <!-- See FIXME for a tutorial on how to write FrontendActions. -->
23In this tutorial, we'll demonstrate the different ways of running clang's
24SyntaxOnlyAction, which runs a quick syntax check, over a bunch of
25code.</p>
26
27<!-- ======================================================================= -->
28<h2 id="runoncode">Parsing a code snippet in memory.</h2>
29<!-- ======================================================================= -->
30
31<p>If you ever wanted to run a FrontendAction over some sample code, for example
32to unit test parts of the Clang AST, runToolOnCode is what you looked for. Let
33me give you an example:
34<pre>
35 #include "clang/Tooling/Tooling.h"
36
37 TEST(runToolOnCode, CanSyntaxCheckCode) {
38 // runToolOnCode returns whether the action was correctly run over the
39 // given code.
40 EXPECT_TRUE(runToolOnCode(new clang::SyntaxOnlyAction, "class X {};"));
41 }
42</pre>
43
44<!-- ======================================================================= -->
45<h2 id="standalonetool">Writing a standalone tool.</h2>
46<!-- ======================================================================= -->
47
48<p>Once you unit tested your FrontendAction to the point where it cannot
49possibly break, it's time to create a standalone tool. For a standalone tool
50to run clang, it first needs to figure out what command line arguments to use
51for a specified file. To that end we create a CompilationDatabase.</p>
52
53<h3 id="compilationdb">Creating a compilation database.</h3>
54<p>CompilationDatabase provides static factory functions to help with parsing
55compile commands from a build directory or the command line. The following code
56allows for both explicit specification of a compile command line, as well as
57retrieving the compile commands lines from a database.
58<pre>
59int main(int argc, const char **argv) {
60 // First, try to create a fixed compile command database from the command line
61 // arguments.
62 llvm::OwningPtr&lt;CompilationDatabase> Compilations(
63 FixedCompilationDatabase::loadFromCommandLine(argc, argv));
64
65 // Next, use normal llvm command line parsing to get the tool specific
66 // parameters.
67 cl::ParseCommandLineOptions(argc, argv);
68
69 if (!Compilations) {
70 // In case the user did not specify the compile command line via positional
71 // command line arguments after "--", try to load the compile commands from
72 // a database in the specified build directory.
73 std::string ErrorMessage;
74 Compilations.reset(CompilationDatabase::loadFromDirectory(BuildPath,
75 ErrorMessage));
76
77 // If there is still no valid compile command database, we don't know how
78 // to run the tool.
79 if (!Compilations)
80 llvm::report_fatal_error(ErrorMessage);
81 }
82...
83}
84</pre>
85</p>
86
87<h3 id="tool">Creating and running a ClangTool.</h3>
88<p>Once we have a CompilationDatabase, we can create a ClangTool and run our
89FrontendAction over some code. For example, to run the SyntaxOnlyAction over
90the files "a.cc" and "b.cc" one would write:
91<pre>
92 // A clang tool can run over a number of sources in the same process...
93 std::vector&lt;std::string> Sources;
94 Sources.push_back("a.cc");
95 Sources.push_back("b.cc");
96
97 // We hand the CompilationDatabase we created and the sources to run over into
98 // the tool constructor.
99 ClangTool Tool(*Compilations, Sources);
100
101 // The ClangTool needs a new FrontendAction for each translation unit we run
102 // on. Thus, it takes a FrontendActionFactory as parameter. To create a
103 // FrontendActionFactory from a given FrontendAction type, we call
104 // newFrontendActionFactory&lt;clang::SyntaxOnlyAction>().
105 int result = Tool.run(newFrontendActionFactory&lt;clang::SyntaxOnlyAction>());
106</pre>
107</p>
108
109<h3 id="main">Putting it together - the first tool.</h3>
110<p>Now we combine the two previous steps into our first real tool. This example
111tool is also checked into the clang tree at tools/clang-check/ClangCheck.cpp.
112<pre>
113 #include "llvm/Support/CommandLine.h"
114 #include "clang/Frontend/FrontendActions.h"
115 #include "clang/Tooling/CompilationDatabase.h"
116 #include "clang/Tooling/Tooling.h"
117
118 using namespace clang::tooling;
119 using namespace llvm;
120
121 cl::opt&lt;std::string> BuildPath(
122 cl::Positional,
123 cl::desc("&lt;build-path>"));
124
125 cl::list&lt;std::string> SourcePaths(
126 cl::Positional,
127 cl::desc("&lt;source0> [... &lt;sourceN>]"),
128 cl::OneOrMore);
129
130 int main(int argc, const char **argv) {
131 llvm::OwningPtr&lt;CompilationDatabase> Compilations(
132 FixedCompilationDatabase::loadFromCommandLine(argc, argv));
133 cl::ParseCommandLineOptions(argc, argv);
134 if (!Compilations) {
135 std::string ErrorMessage;
136 Compilations.reset(CompilationDatabase::loadFromDirectory(BuildPath,
137 ErrorMessage));
138 if (!Compilations)
139 llvm::report_fatal_error(ErrorMessage);
140 }
141 ClangTool Tool(*Compilations, SourcePaths);
142 return Tool.run(newFrontendActionFactory&lt;clang::SyntaxOnlyAction>());
143 }
144</pre>
145</p>
146
147<h3 id="running">Running the tool on some code.</h3>
148<p>When you check out and build clang, clang-check is already built and
149available to you in bin/clang-check inside your build directory.</p>
150<p>You can run clang-check on a file in the llvm repository by specifying
151all the needed parameters after a "--" separator:
152<pre>
153 $ cd /path/to/source/llvm
154 $ export BD=/path/to/build/llvm
155 $ $BD/bin/clang-check . tools/clang/tools/clang-check/ClangCheck.cpp -- \
156 clang++ -D__STDC_CONSTANT_MACROS -D__STDC_LIMIT_MACROS \
157 -Itools/clang/include -I$BD/include -Iinclude -Itools/clang/lib/Headers -c
158</pre>
159</p>
160
161<p>As an alternative, you can also configure cmake to output a compile command
162database into its build directory:
163<pre>
164 # Alternatively to calling cmake, use ccmake, toggle to advanced mode and
165 # set the parameter CMAKE_EXPORT_COMPILE_COMMANDS from the UI.
166 $ cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON .
167</pre>
168</p>
169<p>
170This creates a file called compile_commands.json in the build directory. Now
171you can run clang-check over files in the project by specifying the build path
172as first argument and some source files as further positional arguments:
173<pre>
174 $ cd /path/to/source/llvm
175 $ export BD=/path/to/build/llvm
176 $ $BD/bin/clang-check $BD tools/clang/tools/clang-check/ClangCheck.cpp
177</pre>
178</p>
179
180</div>
181</body>
182</html>
183