Sean Silva | 3872b46 | 2012-12-12 23:44:55 +0000 | [diff] [blame] | 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 |
Sean Silva | 159cc9e | 2013-01-02 13:07:47 +0000 | [diff] [blame] | 10 | :doc:`HowToSetupToolingForLLVM` |
Sean Silva | 3872b46 | 2012-12-12 23:44:55 +0000 | [diff] [blame] | 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 | |
| 64 | using namespace clang::tooling; |
| 65 | |
| 66 | int main(int argc, const char **argv) { |
| 67 | // CommonOptionsParser constructor will parse arguments and create a |
| 68 | // CompilationDatabase. In case of error it will terminate the program. |
| 69 | CommonOptionsParser OptionsParser(argc, argv); |
| 70 | |
Edwin Vane | b1f67db | 2012-12-14 18:58:25 +0000 | [diff] [blame] | 71 | // Use OptionsParser.getCompilations() and OptionsParser.getSourcePathList() |
Sean Silva | 3872b46 | 2012-12-12 23:44:55 +0000 | [diff] [blame] | 72 | // to retrieve CompilationDatabase and the list of input file paths. |
| 73 | } |
| 74 | |
| 75 | Creating and running a ClangTool |
| 76 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 77 | |
| 78 | Once we have a ``CompilationDatabase``, we can create a ``ClangTool`` and run |
| 79 | our ``FrontendAction`` over some code. For example, to run the |
| 80 | ``SyntaxOnlyAction`` over the files "a.cc" and "b.cc" one would write: |
| 81 | |
| 82 | .. code-block:: c++ |
| 83 | |
| 84 | // A clang tool can run over a number of sources in the same process... |
| 85 | std::vector<std::string> Sources; |
| 86 | Sources.push_back("a.cc"); |
| 87 | Sources.push_back("b.cc"); |
| 88 | |
| 89 | // We hand the CompilationDatabase we created and the sources to run over into |
| 90 | // the tool constructor. |
Edwin Vane | b1f67db | 2012-12-14 18:58:25 +0000 | [diff] [blame] | 91 | ClangTool Tool(OptionsParser.getCompilations(), Sources); |
Sean Silva | 3872b46 | 2012-12-12 23:44:55 +0000 | [diff] [blame] | 92 | |
| 93 | // The ClangTool needs a new FrontendAction for each translation unit we run |
| 94 | // on. Thus, it takes a FrontendActionFactory as parameter. To create a |
| 95 | // FrontendActionFactory from a given FrontendAction type, we call |
| 96 | // newFrontendActionFactory<clang::SyntaxOnlyAction>(). |
| 97 | int result = Tool.run(newFrontendActionFactory<clang::SyntaxOnlyAction>()); |
| 98 | |
| 99 | Putting it together --- the first tool |
| 100 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 101 | |
| 102 | Now we combine the two previous steps into our first real tool. This example |
| 103 | tool is also checked into the clang tree at |
| 104 | ``tools/clang-check/ClangCheck.cpp``. |
| 105 | |
| 106 | .. code-block:: c++ |
| 107 | |
| 108 | // Declares clang::SyntaxOnlyAction. |
| 109 | #include "clang/Frontend/FrontendActions.h" |
| 110 | #include "clang/Tooling/CommonOptionsParser.h" |
| 111 | #include "clang/Tooling/Tooling.h" |
| 112 | // Declares llvm::cl::extrahelp. |
| 113 | #include "llvm/Support/CommandLine.h" |
| 114 | |
| 115 | using namespace clang::tooling; |
| 116 | using namespace llvm; |
| 117 | |
| 118 | // CommonOptionsParser declares HelpMessage with a description of the common |
| 119 | // command-line options related to the compilation database and input files. |
| 120 | // It's nice to have this help message in all tools. |
| 121 | static cl::extrahelp CommonHelp(CommonOptionsParser::HelpMessage); |
| 122 | |
| 123 | // A help message for this specific tool can be added afterwards. |
| 124 | static cl::extrahelp MoreHelp("\nMore help text..."); |
| 125 | |
| 126 | int main(int argc, const char **argv) { |
| 127 | CommonOptionsParser OptionsParser(argc, argv); |
Edwin Vane | b1f67db | 2012-12-14 18:58:25 +0000 | [diff] [blame] | 128 | ClangTool Tool(OptionsParser.getCompilations(), |
| 129 | OptionsParser.getSourcePathList()); |
Sean Silva | 3872b46 | 2012-12-12 23:44:55 +0000 | [diff] [blame] | 130 | return Tool.run(newFrontendActionFactory<clang::SyntaxOnlyAction>()); |
| 131 | } |
| 132 | |
| 133 | Running the tool on some code |
| 134 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 135 | |
| 136 | When you check out and build clang, clang-check is already built and available |
| 137 | to you in bin/clang-check inside your build directory. |
| 138 | |
| 139 | You can run clang-check on a file in the llvm repository by specifying all the |
| 140 | needed parameters after a "``--``" separator: |
| 141 | |
| 142 | .. code-block:: bash |
| 143 | |
| 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 \ |
| 149 | -Itools/clang/lib/Headers -c |
| 150 | |
| 151 | As an alternative, you can also configure cmake to output a compile command |
| 152 | database into its build directory: |
| 153 | |
| 154 | .. code-block:: bash |
| 155 | |
| 156 | # Alternatively to calling cmake, use ccmake, toggle to advanced mode and |
| 157 | # set the parameter CMAKE_EXPORT_COMPILE_COMMANDS from the UI. |
| 158 | $ cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON . |
| 159 | |
| 160 | This creates a file called ``compile_commands.json`` in the build directory. |
| 161 | Now you can run :program:`clang-check` over files in the project by specifying |
| 162 | the build path as first argument and some source files as further positional |
| 163 | arguments: |
| 164 | |
| 165 | .. code-block:: bash |
| 166 | |
| 167 | $ cd /path/to/source/llvm |
| 168 | $ export BD=/path/to/build/llvm |
| 169 | $ $BD/bin/clang-check -p $BD tools/clang/tools/clang-check/ClangCheck.cpp |
| 170 | |
| 171 | Builtin includes |
| 172 | ^^^^^^^^^^^^^^^^ |
| 173 | |
| 174 | Clang tools need their builtin headers and search for them the same way Clang |
| 175 | does. Thus, the default location to look for builtin headers is in a path |
Sean Silva | 41f6935 | 2013-01-02 13:25:05 +0000 | [diff] [blame] | 176 | ``$(dirname /path/to/tool)/../lib/clang/3.3/include`` relative to the tool |
Sean Silva | 3872b46 | 2012-12-12 23:44:55 +0000 | [diff] [blame] | 177 | binary. This works out-of-the-box for tools running from llvm's toplevel |
| 178 | binary directory after building clang-headers, or if the tool is running from |
| 179 | the binary directory of a clang install next to the clang binary. |
| 180 | |
| 181 | Tips: if your tool fails to find ``stddef.h`` or similar headers, call the tool |
| 182 | with ``-v`` and look at the search paths it looks through. |
| 183 | |
| 184 | Linking |
| 185 | ^^^^^^^ |
| 186 | |
Sean Silva | 8cbdac6 | 2013-01-02 13:23:37 +0000 | [diff] [blame] | 187 | For a list of libraries to link, look at one of the tools' Makefiles (for |
| 188 | example `clang-check/Makefile |
Sean Silva | 3872b46 | 2012-12-12 23:44:55 +0000 | [diff] [blame] | 189 | <http://llvm.org/viewvc/llvm-project/cfe/trunk/tools/clang-check/Makefile?view=markup>`_). |