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 Defining pragmas
  47 ================
  48
  49 Plugins can also define pragmas by declaring a ``PragmaHandler`` and
  50 registering it using ``PragmaHandlerRegistry::Add<>``:
  51
  52 .. code-block:: c++
  53
  54   // Define a pragma handler for #pragma example_pragma
  55   class ExamplePragmaHandler : public PragmaHandler {
  56   public:
  57     ExamplePragmaHandler() : PragmaHandler("example_pragma") { }
  58     void HandlePragma(Preprocessor &PP, PragmaIntroducer Introducer,
  59                       Token &PragmaTok) {
  60       // Handle the pragma
  61     }
  62   };
  63
  64   static PragmaHandlerRegistry::Add<ExamplePragmaHandler> Y("example_pragma","example pragma description");
  65
  66 Defining attributes
  67 ===================
  68
  69 Plugins can define attributes by declaring a ``ParsedAttrInfo`` and registering
  70 it using ``ParsedAttrInfoRegister::Add<>``:
  71
  72 .. code-block:: c++
  73
  74   class ExampleAttrInfo : public ParsedAttrInfo {
  75   public:
  76     ExampleAttrInfo() {
  77       Spellings.push_back({ParsedAttr::AS_GNU,"example"});
  78     }
  79     AttrHandling handleDeclAttribute(Sema &S, Decl *D,
  80                                      const ParsedAttr &Attr) const override {
  81       // Handle the attribute
  82       return AttributeApplied;
  83     }
  84   };
  85
  86   static ParsedAttrInfoRegistry::Add<ExampleAttrInfo> Z("example_attr","example attribute description");
  87
  88 The members of ``ParsedAttrInfo`` that a plugin attribute must define are:
  89
  90  * ``Spellings``, which must be populated with every `Spelling
  91    </doxygen/structclang_1_1ParsedAttrInfo_1_1Spelling.html>`_ of the
  92    attribute, each of which consists of an attribute syntax and how the
  93    attribute name is spelled for that syntax. If the syntax allows a scope then
  94    the spelling must be "scope::attr" if a scope is present or "::attr" if not.
  95  * ``handleDeclAttribute``, which is the function that applies the attribute to
  96    a declaration. It is responsible for checking that the attribute's arguments
  97    are valid, and typically applies the attribute by adding an ``Attr`` to the
  98    ``Decl``. It returns either ``AttributeApplied``, to indicate that the
  99    attribute was successfully applied, or ``AttributeNotApplied`` if it wasn't.
 100
 101 The members of ``ParsedAttrInfo`` that may need to be defined, depending on the
 102 attribute, are:
 103
 104  * ``NumArgs`` and ``OptArgs``, which set the number of required and optional
 105    arguments to the attribute.
 106  * ``diagAppertainsToDecl``, which checks if the attribute has been used on the
 107    right kind of declaration and issues a diagnostic if not.
 108  * ``diagLangOpts``, which checks if the attribute is permitted for the current
 109    language mode and issues a diagnostic if not.
 110  * ``existsInTarget``, which checks if the attribute is permitted for the given
 111    target.
 112
 113 To see a working example of an attribute plugin, see `the Attribute.cpp example
 114 <https://github.com/llvm/llvm-project/blob/main/clang/examples/Attribute/Attribute.cpp>`_.
 115
 116 Putting it all together
 117 =======================
 118
 119 Let's look at an example plugin that prints top-level function names.  This
 120 example is checked into the clang repository; please take a look at
 121 the `latest version of PrintFunctionNames.cpp
 122 <https://github.com/llvm/llvm-project/blob/main/clang/examples/PrintFunctionNames/PrintFunctionNames.cpp>`_.
 123
 124 Running the plugin
 125 ==================
 126
 127
 128 Using the compiler driver
 129 --------------------------
 130
 131 The Clang driver accepts the `-fplugin` option to load a plugin.
 132 Clang plugins can receive arguments from the compiler driver command
 133 line via the `fplugin-arg-<plugin name>-<argument>` option. Using this
 134 method, the plugin name cannot contain dashes itself, but the argument
 135 passed to the plugin can.
 136
 137
 138 .. code-block:: console
 139
 140   $ export BD=/path/to/build/directory
 141   $ make -C $BD CallSuperAttr
 142   $ clang++ -fplugin=$BD/lib/CallSuperAttr.so \
 143             -fplugin-arg-call_super_plugin-help \
 144             test.cpp
 145
 146 If your plugin name contains dashes, either rename the plugin or used the
 147 cc1 command line options listed below.
 148
 149
 150 Using the cc1 command line
 151 --------------------------
 152
 153 To run a plugin, the dynamic library containing the plugin registry must be
 154 loaded via the `-load` command line option. This will load all plugins
 155 that are registered, and you can select the plugins to run by specifying the
 156 `-plugin` option. Additional parameters for the plugins can be passed with
 157 `-plugin-arg-<plugin-name>`.
 158
 159 Note that those options must reach clang's cc1 process. There are two
 160 ways to do so:
 161
 162 * Directly call the parsing process by using the `-cc1` option; this
 163   has the downside of not configuring the default header search paths, so
 164   you'll need to specify the full system path configuration on the command
 165   line.
 166 * Use clang as usual, but prefix all arguments to the cc1 process with
 167   `-Xclang`.
 168
 169 For example, to run the ``print-function-names`` plugin over a source file in
 170 clang, first build the plugin, and then call clang with the plugin from the
 171 source tree:
 172
 173 .. code-block:: console
 174
 175   $ export BD=/path/to/build/directory
 176   $ (cd $BD && make PrintFunctionNames )
 177   $ clang++ -D_GNU_SOURCE -D_DEBUG -D__STDC_CONSTANT_MACROS \
 178             -D__STDC_FORMAT_MACROS -D__STDC_LIMIT_MACROS -D_GNU_SOURCE \
 179             -I$BD/tools/clang/include -Itools/clang/include -I$BD/include -Iinclude \
 180             tools/clang/tools/clang-check/ClangCheck.cpp -fsyntax-only \
 181             -Xclang -load -Xclang $BD/lib/PrintFunctionNames.so -Xclang \
 182             -plugin -Xclang print-fns
 183
 184 Also see the print-function-name plugin example's
 185 `README <https://github.com/llvm/llvm-project/blob/main/clang/examples/PrintFunctionNames/README.txt>`_
 186
 187
 188 Using the clang command line
 189 ----------------------------
 190
 191 Using `-fplugin=plugin` on the clang command line passes the plugin
 192 through as an argument to `-load` on the cc1 command line. If the plugin
 193 class implements the ``getActionType`` method then the plugin is run
 194 automatically. For example, to run the plugin automatically after the main AST
 195 action (i.e. the same as using `-add-plugin`):
 196
 197 .. code-block:: c++
 198
 199   // Automatically run the plugin after the main AST action
 200   PluginASTAction::ActionType getActionType() override {
 201     return AddAfterMainAction;
 202   }
 203
 204 Interaction with ``-clear-ast-before-backend``
 205 ----------------------------------------------
 206
 207 To reduce peak memory usage of the compiler, plugins are recommended to run
 208 *before* the main action, which is usually code generation. This is because
 209 having any plugins that run after the codegen action automatically turns off
 210 ``-clear-ast-before-backend``.  ``-clear-ast-before-backend`` reduces peak
 211 memory by clearing the Clang AST after generating IR and before running IR
 212 optimizations. Use ``CmdlineBeforeMainAction`` or ``AddBeforeMainAction`` as
 213 ``getActionType`` to run plugins while still benefitting from
 214 ``-clear-ast-before-backend``. Plugins must make sure not to modify the AST,
 215 otherwise they should run after the main action.
 216