1=============
2Clang Plugins
3=============
4
5Clang Plugins make it possible to run extra user defined actions during a
6compilation. This document will provide a basic walkthrough of how to write and
7run a Clang Plugin.
8
9Introduction
10============
11
12Clang Plugins run FrontendActions over code. See the :doc:`FrontendAction
13tutorial <RAVFrontendAction>` on how to write a ``FrontendAction`` using the
14``RecursiveASTVisitor``. In this tutorial, we'll demonstrate how to write a
15simple clang plugin.
16
17Writing a ``PluginASTAction``
18=============================
19
20The main difference from writing normal ``FrontendActions`` is that you can
21handle plugin command line options. The ``PluginASTAction`` base class declares
22a ``ParseArgs`` method which you have to implement in your plugin.
23
24.. code-block:: c++
25
26  bool ParseArgs(const CompilerInstance &CI,
27                 const std::vector<std::string>& args) {
28    for (unsigned i = 0, e = args.size(); i != e; ++i) {
29      if (args[i] == "-some-arg") {
30        // Handle the command line argument.
31      }
32    }
33    return true;
34  }
35
36Registering a plugin
37====================
38
39A plugin is loaded from a dynamic library at runtime by the compiler. To
40register a plugin in a library, use ``FrontendPluginRegistry::Add<>``:
41
42.. code-block:: c++
43
44  static FrontendPluginRegistry::Add<MyPlugin> X("my-plugin-name", "my plugin description");
45
46Putting it all together
47=======================
48
49Let's look at an example plugin that prints top-level function names.  This
50example is checked into the clang repository; please take a look at
51the `latest version of PrintFunctionNames.cpp
52<http://llvm.org/viewvc/llvm-project/cfe/trunk/examples/PrintFunctionNames/PrintFunctionNames.cpp?view=markup>`_.
53
54Running the plugin
55==================
56
57To run a plugin, the dynamic library containing the plugin registry must be
58loaded via the :option:`-load` command line option. This will load all plugins
59that are registered, and you can select the plugins to run by specifying the
60:option:`-plugin` option. Additional parameters for the plugins can be passed with
61:option:`-plugin-arg-<plugin-name>`.
62
63Note that those options must reach clang's cc1 process. There are two
64ways to do so:
65
66* Directly call the parsing process by using the :option:`-cc1` option; this
67  has the downside of not configuring the default header search paths, so
68  you'll need to specify the full system path configuration on the command
69  line.
70* Use clang as usual, but prefix all arguments to the cc1 process with
71  :option:`-Xclang`.
72
73For example, to run the ``print-function-names`` plugin over a source file in
74clang, first build the plugin, and then call clang with the plugin from the
75source tree:
76
77.. code-block:: console
78
79  $ export BD=/path/to/build/directory
80  $ (cd $BD && make PrintFunctionNames )
81  $ clang++ -D_GNU_SOURCE -D_DEBUG -D__STDC_CONSTANT_MACROS \
82            -D__STDC_FORMAT_MACROS -D__STDC_LIMIT_MACROS -D_GNU_SOURCE \
83            -I$BD/tools/clang/include -Itools/clang/include -I$BD/include -Iinclude \
84            tools/clang/tools/clang-check/ClangCheck.cpp -fsyntax-only \
85            -Xclang -load -Xclang $BD/lib/PrintFunctionNames.so -Xclang \
86            -plugin -Xclang print-fns
87
88Also see the print-function-name plugin example's
89`README <http://llvm.org/viewvc/llvm-project/cfe/trunk/examples/PrintFunctionNames/README.txt?view=markup>`_
90
91