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 46Defining pragmas 47================ 48 49Plugins can also define pragmas by declaring a ``PragmaHandler`` and 50registering 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, PragmaIntroducerKind Introducer, 59 Token &PragmaTok) { 60 // Handle the pragma 61 } 62 }; 63 64 static PragmaHandlerRegistry::Add<ExamplePragmaHandler> Y("example_pragma","example pragma description"); 65 66Putting it all together 67======================= 68 69Let's look at an example plugin that prints top-level function names. This 70example is checked into the clang repository; please take a look at 71the `latest version of PrintFunctionNames.cpp 72<http://llvm.org/viewvc/llvm-project/cfe/trunk/examples/PrintFunctionNames/PrintFunctionNames.cpp?view=markup>`_. 73 74Running the plugin 75================== 76 77 78Using the cc1 command line 79-------------------------- 80 81To run a plugin, the dynamic library containing the plugin registry must be 82loaded via the `-load` command line option. This will load all plugins 83that are registered, and you can select the plugins to run by specifying the 84`-plugin` option. Additional parameters for the plugins can be passed with 85`-plugin-arg-<plugin-name>`. 86 87Note that those options must reach clang's cc1 process. There are two 88ways to do so: 89 90* Directly call the parsing process by using the `-cc1` option; this 91 has the downside of not configuring the default header search paths, so 92 you'll need to specify the full system path configuration on the command 93 line. 94* Use clang as usual, but prefix all arguments to the cc1 process with 95 `-Xclang`. 96 97For example, to run the ``print-function-names`` plugin over a source file in 98clang, first build the plugin, and then call clang with the plugin from the 99source tree: 100 101.. code-block:: console 102 103 $ export BD=/path/to/build/directory 104 $ (cd $BD && make PrintFunctionNames ) 105 $ clang++ -D_GNU_SOURCE -D_DEBUG -D__STDC_CONSTANT_MACROS \ 106 -D__STDC_FORMAT_MACROS -D__STDC_LIMIT_MACROS -D_GNU_SOURCE \ 107 -I$BD/tools/clang/include -Itools/clang/include -I$BD/include -Iinclude \ 108 tools/clang/tools/clang-check/ClangCheck.cpp -fsyntax-only \ 109 -Xclang -load -Xclang $BD/lib/PrintFunctionNames.so -Xclang \ 110 -plugin -Xclang print-fns 111 112Also see the print-function-name plugin example's 113`README <http://llvm.org/viewvc/llvm-project/cfe/trunk/examples/PrintFunctionNames/README.txt?view=markup>`_ 114 115 116Using the clang command line 117---------------------------- 118 119Using `-fplugin=plugin` on the clang command line passes the plugin 120through as an argument to `-load` on the cc1 command line. If the plugin 121class implements the ``getActionType`` method then the plugin is run 122automatically. For example, to run the plugin automatically after the main AST 123action (i.e. the same as using `-add-plugin`): 124 125.. code-block:: c++ 126 127 // Automatically run the plugin after the main AST action 128 PluginASTAction::ActionType getActionType() override { 129 return AddAfterMainAction; 130 } 131