external/bsd/llvm/dist/clang/docs/ClangPlugins.rst

   1 =============
   2 Clang Plugins
   3 =============
   4
   5 Clang Plugins make it possible to run extra user defined actions during a
   6 compilation. This document will provide a basic walkthrough of how to write and
   7 run a Clang Plugin.
   8
   9 Introduction
  10 ============
  11
  12 Clang Plugins run FrontendActions over code. See the :doc:`FrontendAction
  13 tutorial <RAVFrontendAction>` on how to write a ``FrontendAction`` using the
  14 ``RecursiveASTVisitor``. In this tutorial, we'll demonstrate how to write a
  15 simple clang plugin.
  16
  17 Writing a ``PluginASTAction``
  18 =============================
  19
  20 The main difference from writing normal ``FrontendActions`` is that you can
  21 handle plugin command line options. The ``PluginASTAction`` base class declares
  22 a ``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
  36 Registering a plugin
  37 ====================
  38
  39 A plugin is loaded from a dynamic library at runtime by the compiler. To
  40 register 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
  46 Putting it all together
  47 =======================
  48
  49 Let's look at an example plugin that prints top-level function names.  This
  50 example is checked into the clang repository; please take a look at
  51 the `latest version of PrintFunctionNames.cpp
  52 <http://llvm.org/viewvc/llvm-project/cfe/trunk/examples/PrintFunctionNames/PrintFunctionNames.cpp?view=markup>`_.
  53
  54 Running the plugin
  55 ==================
  56
  57 To run a plugin, the dynamic library containing the plugin registry must be
  58 loaded via the :option:`-load` command line option. This will load all plugins
  59 that 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
  63 Note that those options must reach clang's cc1 process. There are two
  64 ways 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
  73 For example, to run the ``print-function-names`` plugin over a source file in
  74 clang, first build the plugin, and then call clang with the plugin from the
  75 source 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
  88 Also 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