diff options
Diffstat (limited to 'docs/LibTooling.html')
| -rw-r--r-- | docs/LibTooling.html | 212 |
1 files changed, 0 insertions, 212 deletions
diff --git a/docs/LibTooling.html b/docs/LibTooling.html deleted file mode 100644 index 163d24a..0000000 --- a/docs/LibTooling.html +++ /dev/null @@ -1,212 +0,0 @@ -<!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> -<p>For the information on how to setup Clang Tooling for LLVM see -<a href="HowToSetupToolingForLLVM.html">HowToSetupToolingForLLVM.html</a></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 -code.</p> - -<!-- ======================================================================= --> -<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: -<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 <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. -</p> - -<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. -<pre> -#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. -} -</pre> -</p> - -<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 "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(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<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> -// Declares clang::SyntaxOnlyAction. -#include "clang/Frontend/FrontendActions.h" -#include "clang/Tooling/CommonOptionsParser.h" -#include "clang/Tooling/Tooling.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(), - OptionsParser.GetSourcePathList()); - 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> - |
