diff options
| author | Manuel Klimek <klimek@google.com> | 2012-04-25 14:20:13 +0000 |
|---|---|---|
| committer | Manuel Klimek <klimek@google.com> | 2012-04-25 14:20:13 +0000 |
| commit | 85e60b5dc9e4dde87e779b572b3555ef535a509d (patch) | |
| tree | 811d51ee3cf417c9ef27a693fa8db2b9481c1d02 | |
| parent | 06b0a7369fa4be5bfb19fe8db2ffb4ac5377e4a8 (diff) | |
| download | bcm5719-llvm-85e60b5dc9e4dde87e779b572b3555ef535a509d.tar.gz bcm5719-llvm-85e60b5dc9e4dde87e779b572b3555ef535a509d.zip | |
Adds documentation for how to use the tooling library.
llvm-svn: 155550
| -rw-r--r-- | clang/docs/LibTooling.html | 183 |
1 files changed, 183 insertions, 0 deletions
diff --git a/clang/docs/LibTooling.html b/clang/docs/LibTooling.html new file mode 100644 index 00000000000..5be61fa50b5 --- /dev/null +++ b/clang/docs/LibTooling.html @@ -0,0 +1,183 @@ +<!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> +<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 + // a database in the specified build directory. + std::string ErrorMessage; + Compilations.reset(CompilationDatabase::loadFromDirectory(BuildPath, + ErrorMessage)); + + // 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> + #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( + cl::Positional, + cl::desc("<build-path>")); + + 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; + Compilations.reset(CompilationDatabase::loadFromDirectory(BuildPath, + ErrorMessage)); + if (!Compilations) + llvm::report_fatal_error(ErrorMessage); + } + ClangTool Tool(*Compilations, SourcePaths); + 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 $BD tools/clang/tools/clang-check/ClangCheck.cpp +</pre> +</p> + +</div> +</body> +</html> + |
