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
  96 The members of ``ParsedAttrInfo`` that may need to be defined, depending on the
  97 attribute, are:
  98
  99  * ``NumArgs`` and ``OptArgs``, which set the number of required and optional
 100    arguments to the attribute.
 101  * ``diagAppertainsToDecl``, which checks if the attribute has been used on the
 102    right kind of declaration and issues a diagnostic if not.
 103  * ``handleDeclAttribute``, which is the function that applies the attribute to
 104    a declaration. It is responsible for checking that the attribute's arguments
 105    are valid, and typically applies the attribute by adding an ``Attr`` to the
 106    ``Decl``. It returns either ``AttributeApplied``, to indicate that the
 107    attribute was successfully applied, or ``AttributeNotApplied`` if it wasn't.
 108  * ``diagAppertainsToStmt``, which checks if the attribute has been used on the
 109    right kind of statement and issues a diagnostic if not.
 110  * ``handleStmtAttribute``, which is the function that applies the attribute to
 111    a statement. It is responsible for checking that the attribute's arguments
 112    are valid, and typically applies the attribute by adding an ``Attr`` to the
 113    ``Stmt``. It returns either ``AttributeApplied``, to indicate that the
 114    attribute was successfully applied, or ``AttributeNotApplied`` if it wasn't.
 115  * ``diagLangOpts``, which checks if the attribute is permitted for the current
 116    language mode and issues a diagnostic if not.
 117  * ``existsInTarget``, which checks if the attribute is permitted for the given
 118    target.
 119
 120 To see a working example of an attribute plugin, see `the Attribute.cpp example
 121 <https://github.com/llvm/llvm-project/blob/main/clang/examples/Attribute/Attribute.cpp>`_.
 122
 123 Putting it all together
 124 =======================
 125
 126 Let's look at an example plugin that prints top-level function names.  This
 127 example is checked into the clang repository; please take a look at
 128 the `latest version of PrintFunctionNames.cpp
 129 <https://github.com/llvm/llvm-project/blob/main/clang/examples/PrintFunctionNames/PrintFunctionNames.cpp>`_.
 130
 131 Running the plugin
 132 ==================
 133
 134
 135 Using the compiler driver
 136 --------------------------
 137
 138 The Clang driver accepts the `-fplugin` option to load a plugin.
 139 Clang plugins can receive arguments from the compiler driver command
 140 line via the `fplugin-arg-<plugin name>-<argument>` option. Using this
 141 method, the plugin name cannot contain dashes itself, but the argument
 142 passed to the plugin can.
 143
 144
 145 .. code-block:: console
 146
 147   $ export BD=/path/to/build/directory
 148   $ make -C $BD CallSuperAttr
 149   $ clang++ -fplugin=$BD/lib/CallSuperAttr.so \
 150             -fplugin-arg-call_super_plugin-help \
 151             test.cpp
 152
 153 If your plugin name contains dashes, either rename the plugin or used the
 154 cc1 command line options listed below.
 155
 156
 157 Using the cc1 command line
 158 --------------------------
 159
 160 To run a plugin, the dynamic library containing the plugin registry must be
 161 loaded via the `-load` command line option. This will load all plugins
 162 that are registered, and you can select the plugins to run by specifying the
 163 `-plugin` option. Additional parameters for the plugins can be passed with
 164 `-plugin-arg-<plugin-name>`.
 165
 166 Note that those options must reach clang's cc1 process. There are two
 167 ways to do so:
 168
 169 * Directly call the parsing process by using the `-cc1` option; this
 170   has the downside of not configuring the default header search paths, so
 171   you'll need to specify the full system path configuration on the command
 172   line.
 173 * Use clang as usual, but prefix all arguments to the cc1 process with
 174   `-Xclang`.
 175
 176 For example, to run the ``print-function-names`` plugin over a source file in
 177 clang, first build the plugin, and then call clang with the plugin from the
 178 source tree:
 179
 180 .. code-block:: console
 181
 182   $ export BD=/path/to/build/directory
 183   $ (cd $BD && make PrintFunctionNames )
 184   $ clang++ -D_GNU_SOURCE -D_DEBUG -D__STDC_CONSTANT_MACROS \
 185             -D__STDC_FORMAT_MACROS -D__STDC_LIMIT_MACROS -D_GNU_SOURCE \
 186             -I$BD/tools/clang/include -Itools/clang/include -I$BD/include -Iinclude \
 187             tools/clang/tools/clang-check/ClangCheck.cpp -fsyntax-only \
 188             -Xclang -load -Xclang $BD/lib/PrintFunctionNames.so -Xclang \
 189             -plugin -Xclang print-fns
 190
 191 Also see the print-function-name plugin example's
 192 `README <https://github.com/llvm/llvm-project/blob/main/clang/examples/PrintFunctionNames/README.txt>`_
 193
 194
 195 Using the clang command line
 196 ----------------------------
 197
 198 Using `-fplugin=plugin` on the clang command line passes the plugin
 199 through as an argument to `-load` on the cc1 command line. If the plugin
 200 class implements the ``getActionType`` method then the plugin is run
 201 automatically. For example, to run the plugin automatically after the main AST
 202 action (i.e. the same as using `-add-plugin`):
 203
 204 .. code-block:: c++
 205
 206   // Automatically run the plugin after the main AST action
 207   PluginASTAction::ActionType getActionType() override {
 208     return AddAfterMainAction;
 209   }
 210
 211 Interaction with ``-clear-ast-before-backend``
 212 ----------------------------------------------
 213
 214 To reduce peak memory usage of the compiler, plugins are recommended to run
 215 *before* the main action, which is usually code generation. This is because
 216 having any plugins that run after the codegen action automatically turns off
 217 ``-clear-ast-before-backend``.  ``-clear-ast-before-backend`` reduces peak
 218 memory by clearing the Clang AST after generating IR and before running IR
 219 optimizations. Use ``CmdlineBeforeMainAction`` or ``AddBeforeMainAction`` as
 220 ``getActionType`` to run plugins while still benefitting from
 221 ``-clear-ast-before-backend``. Plugins must make sure not to modify the AST,
 222 otherwise they should run after the main action.
 223