diff options
Diffstat (limited to 'docs/LibTooling.html')
| -rw-r--r-- | docs/LibTooling.html | 229 |
1 files changed, 229 insertions, 0 deletions
diff --git a/docs/LibTooling.html b/docs/LibTooling.html new file mode 100644 index 0000000..ed0ad45 --- /dev/null +++ b/docs/LibTooling.html @@ -0,0 +1,229 @@ +<!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> + +<!-- ======================================================================= --> +<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 or auto-detect it from a + // source file. + std::string ErrorMessage; + if (!BuildPath.empty()) { + Compilations.reset( + CompilationDatabase::autoDetectFromDirectory(BuildPath, ErrorMessage)); + } else { + Compilations.reset(CompilationDatabase::autoDetectFromSource( + SourcePaths[0], 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( + "p", + cl::desc("<build-path>"), + cl::Optional); + +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( + !BuildPath.empty() ? + CompilationDatabase::autoDetectFromDirectory(BuildPath, ErrorMessage) : + CompilationDatabase::autoDetectFromSource(SourcePaths[0], 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 -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> + |
