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