blob: d896a5f8857620767837d8d1c8194ee255d1efa7 [file] [log] [blame]
<link type="text/css" rel="stylesheet" href="../menu.css">
<link type="text/css" rel="stylesheet" href="../content.css">
<!--#include virtual="../menu.html.incl"-->
<div id="content">
<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
<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
<!-- ======================================================================= -->
<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:
#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 {};"));
<!-- ======================================================================= -->
<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.
<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.
#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.
<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 "" and
"" one would write:
// A clang tool can run over a number of sources in the same process...
std::vector&lt;std::string> Sources;
// 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&lt;clang::SyntaxOnlyAction>().
int result =;clang::SyntaxOnlyAction>());
<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.
// Declares clang::SyntaxOnlyAction.
#include "clang/Frontend/FrontendActions.h"
#include "clang/Tooling/CommonOptionsParser.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(),
<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:
$ cd /path/to/source/llvm
$ export BD=/path/to/build/llvm
$ $BD/bin/clang-check tools/clang/tools/clang-check/ClangCheck.cpp -- \
-Itools/clang/include -I$BD/include -Iinclude -Itools/clang/lib/Headers -c
<p>As an alternative, you can also configure cmake to output a compile command
database into its build directory:
# Alternatively to calling cmake, use ccmake, toggle to advanced mode and
# set the parameter CMAKE_EXPORT_COMPILE_COMMANDS from the UI.
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:
$ cd /path/to/source/llvm
$ export BD=/path/to/build/llvm
$ $BD/bin/clang-check -p $BD tools/clang/tools/clang-check/ClangCheck.cpp
<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="">clang-check/Makefile</a>).
<p>To link a binary using the tooling infrastructure, link in the following