1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" 2 "http://www.w3.org/TR/html4/strict.dtd"> 3 <html> 4 <head> 5 <title>LibTooling</title> 6 <link type="text/css" rel="stylesheet" href="../menu.css"> 7 <link type="text/css" rel="stylesheet" href="../content.css"> 8 </head> 9 <body> 10 11 <!--#include virtual="../menu.html.incl"--> 12 13 <div id="content"> 14 15 <h1>LibTooling</h1> 16 <p>LibTooling is a library to support writing standalone tools based on 17 Clang. This document will provide a basic walkthrough of how to write 18 a tool using LibTooling.</p> 19 20 <!-- ======================================================================= --> 21 <h2 id="intro">Introduction</h2> 22 <!-- ======================================================================= --> 23 24 <p>Tools built with LibTooling, like Clang Plugins, run 25 <code>FrontendActions</code> over code. 26 <!-- See FIXME for a tutorial on how to write FrontendActions. --> 27 In this tutorial, we'll demonstrate the different ways of running clang's 28 <code>SyntaxOnlyAction</code>, which runs a quick syntax check, over a bunch of 29 code.</p> 30 31 <!-- ======================================================================= --> 32 <h2 id="runoncode">Parsing a code snippet in memory.</h2> 33 <!-- ======================================================================= --> 34 35 <p>If you ever wanted to run a <code>FrontendAction</code> over some sample 36 code, for example to unit test parts of the Clang AST, 37 <code>runToolOnCode</code> is what you looked for. Let me give you an example: 38 <pre> 39 #include "clang/Tooling/Tooling.h" 40 41 TEST(runToolOnCode, CanSyntaxCheckCode) { 42 // runToolOnCode returns whether the action was correctly run over the 43 // given code. 44 EXPECT_TRUE(runToolOnCode(new clang::SyntaxOnlyAction, "class X {};")); 45 } 46 </pre> 47 48 <!-- ======================================================================= --> 49 <h2 id="standalonetool">Writing a standalone tool.</h2> 50 <!-- ======================================================================= --> 51 52 <p>Once you unit tested your <code>FrontendAction</code> to the point where it 53 cannot possibly break, it's time to create a standalone tool. For a standalone 54 tool to run clang, it first needs to figure out what command line arguments to 55 use for a specified file. To that end we create a 56 <code>CompilationDatabase</code>. There are different ways to create a 57 compilation database, and we need to support all of them depending on 58 command-line options. There's the <code>CommonOptionsParser</code> class 59 that takes the responsibility to parse command-line parameters related to 60 compilation databases and inputs, so that all tools share the implementation. 61 </p> 62 63 <h3 id="parsingcommonoptions">Parsing common tools options.</h3> 64 <p><code>CompilationDatabase</code> can be read from a build directory or the 65 command line. Using <code>CommonOptionsParser</code> allows for explicit 66 specification of a compile command line, specification of build path using the 67 <code>-p</code> command-line option, and automatic location of the compilation 68 database using source files paths. 69 <pre> 70 #include "clang/Tooling/CommonOptionsParser.h" 71 72 using namespace clang::tooling; 73 74 int main(int argc, const char **argv) { 75 // CommonOptionsParser constructor will parse arguments and create a 76 // CompilationDatabase. In case of error it will terminate the program. 77 CommonOptionsParser OptionsParser(argc, argv); 78 79 // Use OptionsParser.GetCompilations() and OptionsParser.GetSourcePathList() 80 // to retrieve CompilationDatabase and the list of input file paths. 81 } 82 </pre> 83 </p> 84 85 <h3 id="tool">Creating and running a ClangTool.</h3> 86 <p>Once we have a <code>CompilationDatabase</code>, we can create a 87 <code>ClangTool</code> and run our <code>FrontendAction</code> over some code. 88 For example, to run the <code>SyntaxOnlyAction</code> over the files "a.cc" and 89 "b.cc" one would write: 90 <pre> 91 // A clang tool can run over a number of sources in the same process... 92 std::vector<std::string> Sources; 93 Sources.push_back("a.cc"); 94 Sources.push_back("b.cc"); 95 96 // We hand the CompilationDatabase we created and the sources to run over into 97 // the tool constructor. 98 ClangTool Tool(OptionsParser.GetCompilations(), Sources); 99 100 // The ClangTool needs a new FrontendAction for each translation unit we run 101 // on. Thus, it takes a FrontendActionFactory as parameter. To create a 102 // FrontendActionFactory from a given FrontendAction type, we call 103 // newFrontendActionFactory<clang::SyntaxOnlyAction>(). 104 int result = Tool.run(newFrontendActionFactory<clang::SyntaxOnlyAction>()); 105 </pre> 106 </p> 107 108 <h3 id="main">Putting it together - the first tool.</h3> 109 <p>Now we combine the two previous steps into our first real tool. This example 110 tool is also checked into the clang tree at tools/clang-check/ClangCheck.cpp. 111 <pre> 112 // Declares clang::SyntaxOnlyAction. 113 #include "clang/Frontend/FrontendActions.h" 114 #include "clang/Tooling/CommonOptionsParser.h" 115 // Declares llvm::cl::extrahelp. 116 #include "llvm/Support/CommandLine.h" 117 118 using namespace clang::tooling; 119 using namespace llvm; 120 121 // CommonOptionsParser declares HelpMessage with a description of the common 122 // command-line options related to the compilation database and input files. 123 // It's nice to have this help message in all tools. 124 static cl::extrahelp CommonHelp(CommonOptionsParser::HelpMessage); 125 126 // A help message for this specific tool can be added afterwards. 127 static cl::extrahelp MoreHelp("\nMore help text..."); 128 129 int main(int argc, const char **argv) { 130 CommonOptionsParser OptionsParser(argc, argv); 131 ClangTool Tool(OptionsParser.GetCompilations(), 132 OptionsParser.GetSourcePathList()); 133 return Tool.run(newFrontendActionFactory<clang::SyntaxOnlyAction>()); 134 } 135 </pre> 136 </p> 137 138 <h3 id="running">Running the tool on some code.</h3> 139 <p>When you check out and build clang, clang-check is already built and 140 available to you in bin/clang-check inside your build directory.</p> 141 <p>You can run clang-check on a file in the llvm repository by specifying 142 all the needed parameters after a "--" separator: 143 <pre> 144 $ cd /path/to/source/llvm 145 $ export BD=/path/to/build/llvm 146 $ $BD/bin/clang-check tools/clang/tools/clang-check/ClangCheck.cpp -- \ 147 clang++ -D__STDC_CONSTANT_MACROS -D__STDC_LIMIT_MACROS \ 148 -Itools/clang/include -I$BD/include -Iinclude -Itools/clang/lib/Headers -c 149 </pre> 150 </p> 151 152 <p>As an alternative, you can also configure cmake to output a compile command 153 database into its build directory: 154 <pre> 155 # Alternatively to calling cmake, use ccmake, toggle to advanced mode and 156 # set the parameter CMAKE_EXPORT_COMPILE_COMMANDS from the UI. 157 $ cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON . 158 </pre> 159 </p> 160 <p> 161 This creates a file called compile_commands.json in the build directory. Now 162 you can run clang-check over files in the project by specifying the build path 163 as first argument and some source files as further positional arguments: 164 <pre> 165 $ cd /path/to/source/llvm 166 $ export BD=/path/to/build/llvm 167 $ $BD/bin/clang-check -p $BD tools/clang/tools/clang-check/ClangCheck.cpp 168 </pre> 169 </p> 170 171 <h3 id="builtin">Builtin includes.</h3> 172 <p>Clang tools need their builtin headers and search for them the same way clang 173 does. Thus, the default location to look for builtin headers is in a path 174 $(dirname /path/to/tool)/../lib/clang/3.2/include relative to the tool 175 binary. This works out-of-the-box for tools running from llvm's toplevel 176 binary directory after building clang-headers, or if the tool is running 177 from the binary directory of a clang install next to the clang binary.</p> 178 179 <p>Tips: if your tool fails to find stddef.h or similar headers, call 180 the tool with -v and look at the search paths it looks through.</p> 181 182 <h3 id="linking">Linking.</h3> 183 <p>Please note that this presents the linking requirements at the time of this 184 writing. For the most up-to-date information, look at one of the tools' 185 Makefiles (for example 186 <a href="http://llvm.org/viewvc/llvm-project/cfe/trunk/tools/clang-check/Makefile?view=markup">clang-check/Makefile</a>). 187 </p> 188 189 <p>To link a binary using the tooling infrastructure, link in the following 190 libraries: 191 <ul> 192 <li>Tooling</li> 193 <li>Frontend</li> 194 <li>Driver</li> 195 <li>Serialization</li> 196 <li>Parse</li> 197 <li>Sema</li> 198 <li>Analysis</li> 199 <li>Edit</li> 200 <li>AST</li> 201 <li>Lex</li> 202 <li>Basic</li> 203 </ul> 204 </p> 205 206 </div> 207 </body> 208 </html> 209 210
