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 91
