2012-04-25 22:20:13 +08:00
|
|
|
<!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>
|
2012-05-25 01:16:23 +08:00
|
|
|
|
|
|
|
|
<!--#include virtual="../menu.html.incl"-->
|
|
|
|
|
|
2012-04-25 22:20:13 +08:00
|
|
|
<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 FrontendActions 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
|
|
|
|
|
SyntaxOnlyAction, 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 FrontendAction over some sample code, for example
|
|
|
|
|
to unit test parts of the Clang AST, runToolOnCode 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 FrontendAction 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 CompilationDatabase.</p>
|
|
|
|
|
|
|
|
|
|
<h3 id="compilationdb">Creating a compilation database.</h3>
|
|
|
|
|
<p>CompilationDatabase provides static factory functions to help with parsing
|
|
|
|
|
compile commands from a build directory or the command line. The following code
|
|
|
|
|
allows for both explicit specification of a compile command line, as well as
|
|
|
|
|
retrieving the compile commands lines from a database.
|
|
|
|
|
<pre>
|
|
|
|
|
int main(int argc, const char **argv) {
|
|
|
|
|
// First, try to create a fixed compile command database from the command line
|
|
|
|
|
// arguments.
|
|
|
|
|
llvm::OwningPtr<CompilationDatabase> Compilations(
|
|
|
|
|
FixedCompilationDatabase::loadFromCommandLine(argc, argv));
|
|
|
|
|
|
|
|
|
|
// Next, use normal llvm command line parsing to get the tool specific
|
|
|
|
|
// parameters.
|
|
|
|
|
cl::ParseCommandLineOptions(argc, argv);
|
|
|
|
|
|
|
|
|
|
if (!Compilations) {
|
|
|
|
|
// In case the user did not specify the compile command line via positional
|
|
|
|
|
// command line arguments after "--", try to load the compile commands from
|
2012-07-13 02:32:50 +08:00
|
|
|
// a database in the specified build directory or auto-detect it from a
|
|
|
|
|
// source file.
|
2012-04-25 22:20:13 +08:00
|
|
|
std::string ErrorMessage;
|
2012-07-13 02:32:50 +08:00
|
|
|
if (!BuildPath.empty()) {
|
|
|
|
|
Compilations.reset(
|
|
|
|
|
CompilationDatabase::autoDetectFromDirectory(BuildPath, ErrorMessage));
|
|
|
|
|
} else {
|
|
|
|
|
Compilations.reset(CompilationDatabase::autoDetectFromSource(
|
|
|
|
|
SourcePaths[0], ErrorMessage));
|
|
|
|
|
}
|
2012-04-25 22:20:13 +08:00
|
|
|
// If there is still no valid compile command database, we don't know how
|
|
|
|
|
// to run the tool.
|
|
|
|
|
if (!Compilations)
|
|
|
|
|
llvm::report_fatal_error(ErrorMessage);
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
</pre>
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<h3 id="tool">Creating and running a ClangTool.</h3>
|
|
|
|
|
<p>Once we have a CompilationDatabase, we can create a ClangTool and run our
|
|
|
|
|
FrontendAction over some code. For example, to run the SyntaxOnlyAction 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(*Compilations, 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>
|
2012-07-13 02:32:50 +08:00
|
|
|
#include "llvm/Support/CommandLine.h"
|
|
|
|
|
#include "clang/Frontend/FrontendActions.h"
|
|
|
|
|
#include "clang/Tooling/CompilationDatabase.h"
|
|
|
|
|
#include "clang/Tooling/Tooling.h"
|
|
|
|
|
|
|
|
|
|
using namespace clang::tooling;
|
|
|
|
|
using namespace llvm;
|
|
|
|
|
|
|
|
|
|
cl::opt<std::string> BuildPath(
|
|
|
|
|
"p",
|
|
|
|
|
cl::desc("<build-path>"),
|
|
|
|
|
cl::Optional);
|
2012-04-25 22:20:13 +08:00
|
|
|
|
2012-07-13 02:32:50 +08:00
|
|
|
cl::list<std::string> SourcePaths(
|
|
|
|
|
cl::Positional,
|
|
|
|
|
cl::desc("<source0> [... <sourceN>]"),
|
|
|
|
|
cl::OneOrMore);
|
|
|
|
|
|
|
|
|
|
int main(int argc, const char **argv) {
|
|
|
|
|
llvm::OwningPtr<CompilationDatabase> Compilations(
|
|
|
|
|
FixedCompilationDatabase::loadFromCommandLine(argc, argv));
|
|
|
|
|
cl::ParseCommandLineOptions(argc, argv);
|
|
|
|
|
if (!Compilations) {
|
|
|
|
|
std::string ErrorMessage;
|
2012-08-14 02:56:38 +08:00
|
|
|
Compilations.reset(
|
|
|
|
|
!BuildPath.empty() ?
|
|
|
|
|
CompilationDatabase::autoDetectFromDirectory(BuildPath, ErrorMessage) :
|
|
|
|
|
CompilationDatabase::autoDetectFromSource(SourcePaths[0], ErrorMessage)
|
|
|
|
|
);
|
2012-07-13 02:32:50 +08:00
|
|
|
if (!Compilations)
|
|
|
|
|
llvm::report_fatal_error(ErrorMessage);
|
2012-04-25 22:20:13 +08:00
|
|
|
}
|
2012-07-13 02:32:50 +08:00
|
|
|
ClangTool Tool(*Compilations, SourcePaths);
|
|
|
|
|
return Tool.run(newFrontendActionFactory<clang::SyntaxOnlyAction>());
|
|
|
|
|
}
|
2012-04-25 22:20:13 +08:00
|
|
|
</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
|
2012-07-13 02:32:50 +08:00
|
|
|
$ $BD/bin/clang-check tools/clang/tools/clang-check/ClangCheck.cpp -- \
|
2012-04-25 22:20:13 +08:00
|
|
|
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
|
2012-07-13 02:32:50 +08:00
|
|
|
$ $BD/bin/clang-check -p $BD tools/clang/tools/clang-check/ClangCheck.cpp
|
2012-04-25 22:20:13 +08:00
|
|
|
</pre>
|
|
|
|
|
</p>
|
|
|
|
|
|
2012-07-13 02:32:50 +08:00
|
|
|
<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>
|
|
|
|
|
|
2012-06-07 01:51:31 +08:00
|
|
|
<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>
|
2012-06-07 05:30:34 +08:00
|
|
|
<li>Tooling</li>
|
2012-06-07 01:51:31 +08:00
|
|
|
<li>Frontend</li>
|
2012-06-07 05:30:34 +08:00
|
|
|
<li>Driver</li>
|
|
|
|
|
<li>Serialization</li>
|
2012-06-07 01:51:31 +08:00
|
|
|
<li>Parse</li>
|
|
|
|
|
<li>Sema</li>
|
2012-06-07 05:30:34 +08:00
|
|
|
<li>Analysis</li>
|
|
|
|
|
<li>Edit</li>
|
|
|
|
|
<li>AST</li>
|
|
|
|
|
<li>Lex</li>
|
|
|
|
|
<li>Basic</li>
|
2012-06-07 01:51:31 +08:00
|
|
|
</ul>
|
|
|
|
|
</p>
|
|
|
|
|
|
2012-04-25 22:20:13 +08:00
|
|
|
</div>
|
|
|
|
|
</body>
|
|
|
|
|
</html>
|
|
|
|
|
|
