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, PragmaIntroducerKind Introducer, 59 Token &PragmaTok) { 60 // Handle the pragma 61 } 62 }; 63 64 static PragmaHandlerRegistry::Add<ExamplePragmaHandler> Y("example_pragma","example pragma description"); 65 66 Putting it all together 67 ======================= 68 69 Let's look at an example plugin that prints top-level function names. This 70 example is checked into the clang repository; please take a look at 71 the `latest version of PrintFunctionNames.cpp 72 <http://llvm.org/viewvc/llvm-project/cfe/trunk/examples/PrintFunctionNames/PrintFunctionNames.cpp?view=markup>`_. 73 74 Running the plugin 75 ================== 76 77 78 Using the cc1 command line 79 -------------------------- 80 81 To run a plugin, the dynamic library containing the plugin registry must be 82 loaded via the `-load` command line option. This will load all plugins 83 that 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 87 Note that those options must reach clang's cc1 process. There are two 88 ways 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 97 For example, to run the ``print-function-names`` plugin over a source file in 98 clang, first build the plugin, and then call clang with the plugin from the 99 source 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 112 Also 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 116 Using the clang command line 117 ---------------------------- 118 119 Using `-fplugin=plugin` on the clang command line passes the plugin 120 through as an argument to `-load` on the cc1 command line. If the plugin 121 class implements the ``getActionType`` method then the plugin is run 122 automatically. For example, to run the plugin automatically after the main AST 123 action (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
