Clang Project

clang_source_code/docs/LibTooling.rst
1==========
2LibTooling
3==========
4
5LibTooling is a library to support writing standalone tools based on Clang.
6This document will provide a basic walkthrough of how to write a tool using
7LibTooling.
8
9For the information on how to setup Clang Tooling for LLVM see
10:doc:`HowToSetupToolingForLLVM`
11
12Introduction
13------------
14
15Tools built with LibTooling, like Clang Plugins, run ``FrontendActions`` over
16code.
17
18..  See FIXME for a tutorial on how to write FrontendActions.
19
20In 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
23Parsing a code snippet in memory
24--------------------------------
25
26If you ever wanted to run a ``FrontendAction`` over some sample code, for
27example to unit test parts of the Clang AST, ``runToolOnCode`` is what you
28looked 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
40Writing a standalone tool
41-------------------------
42
43Once you unit tested your ``FrontendAction`` to the point where it cannot
44possibly break, it's time to create a standalone tool.  For a standalone tool
45to run clang, it first needs to figure out what command line arguments to use
46for a specified file.  To that end we create a ``CompilationDatabase``.  There
47are different ways to create a compilation database, and we need to support all
48of them depending on command-line options.  There's the ``CommonOptionsParser``
49class that takes the responsibility to parse command-line parameters related to
50compilation databases and inputs, so that all tools share the implementation.
51
52Parsing common tools options
53^^^^^^^^^^^^^^^^^^^^^^^^^^^^
54
55``CompilationDatabase`` can be read from a build directory or the command line.
56Using ``CommonOptionsParser`` allows for explicit specification of a compile
57command line, specification of build path using the ``-p`` command-line option,
58and 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
80Creating and running a ClangTool
81^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
82
83Once we have a ``CompilationDatabase``, we can create a ``ClangTool`` and run
84our ``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
104Putting it together --- the first tool
105^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
106
107Now we combine the two previous steps into our first real tool.  A more advanced
108version 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...\n");
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
142Running the tool on some code
143^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
144
145When you check out and build clang, clang-check is already built and available
146to you in bin/clang-check inside your build directory.
147
148You can run clang-check on a file in the llvm repository by specifying all the
149needed 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
160As an alternative, you can also configure cmake to output a compile command
161database 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
169This creates a file called ``compile_commands.json`` in the build directory.
170Now you can run :program:`clang-check` over files in the project by specifying
171the build path as first argument and some source files as further positional
172arguments:
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
183Builtin includes
184^^^^^^^^^^^^^^^^
185
186Clang tools need their builtin headers and search for them the same way Clang
187does.  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
189binary.  This works out-of-the-box for tools running from llvm's toplevel
190binary directory after building clang-resource-headers, or if the tool is
191running from the binary directory of a clang install next to the clang binary.
192
193Tips: if your tool fails to find ``stddef.h`` or similar headers, call the tool
194with ``-v`` and look at the search paths it looks through.
195
196Linking
197^^^^^^^
198
199For a list of libraries to link, look at one of the tools' CMake files (for
200example `clang-check/CMakeList.txt
201<https://github.com/llvm/llvm-project/blob/master/clang/tools/clang-check/CMakeLists.txt>`_).
202
CodeThinker, Enjoy your reading code