Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 1 | ============= |
| 2 | Clang Plugins |
| 3 | ============= |
| 4 | |
Dmitri Gribenko | 97555a1 | 2012-12-15 21:10:51 +0000 | [diff] [blame] | 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. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 8 | |
| 9 | Introduction |
| 10 | ============ |
| 11 | |
| 12 | Clang Plugins run FrontendActions over code. See the :doc:`FrontendAction |
Dmitri Gribenko | 97555a1 | 2012-12-15 21:10:51 +0000 | [diff] [blame] | 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. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 16 | |
Dmitri Gribenko | 97555a1 | 2012-12-15 21:10:51 +0000 | [diff] [blame] | 17 | Writing a ``PluginASTAction`` |
| 18 | ============================= |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 19 | |
Dmitri Gribenko | 97555a1 | 2012-12-15 21:10:51 +0000 | [diff] [blame] | 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. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 23 | |
Dmitri Gribenko | 97555a1 | 2012-12-15 21:10:51 +0000 | [diff] [blame] | 24 | .. code-block:: c++ |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 25 | |
Dmitri Gribenko | 97555a1 | 2012-12-15 21:10:51 +0000 | [diff] [blame] | 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. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 31 | } |
Dmitri Gribenko | 97555a1 | 2012-12-15 21:10:51 +0000 | [diff] [blame] | 32 | } |
| 33 | return true; |
| 34 | } |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 35 | |
| 36 | Registering a plugin |
| 37 | ==================== |
| 38 | |
| 39 | A plugin is loaded from a dynamic library at runtime by the compiler. To |
Dmitri Gribenko | 97555a1 | 2012-12-15 21:10:51 +0000 | [diff] [blame] | 40 | register a plugin in a library, use ``FrontendPluginRegistry::Add<>``: |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 41 | |
Dmitri Gribenko | 97555a1 | 2012-12-15 21:10:51 +0000 | [diff] [blame] | 42 | .. code-block:: c++ |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 43 | |
Dmitri Gribenko | 97555a1 | 2012-12-15 21:10:51 +0000 | [diff] [blame] | 44 | static FrontendPluginRegistry::Add<MyPlugin> X("my-plugin-name", "my plugin description"); |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 45 | |
| 46 | Putting it all together |
| 47 | ======================= |
| 48 | |
Dmitri Gribenko | 97555a1 | 2012-12-15 21:10:51 +0000 | [diff] [blame] | 49 | Let's look at an example plugin that prints top-level function names. This |
Stephen Hines | 651f13c | 2014-04-23 16:59:28 -0700 | [diff] [blame] | 50 | example is checked into the clang repository; please take a look at |
| 51 | the `latest version of PrintFunctionNames.cpp |
Dmitri Gribenko | 97555a1 | 2012-12-15 21:10:51 +0000 | [diff] [blame] | 52 | <http://llvm.org/viewvc/llvm-project/cfe/trunk/examples/PrintFunctionNames/PrintFunctionNames.cpp?view=markup>`_. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 53 | |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 54 | Running the plugin |
| 55 | ================== |
| 56 | |
Dmitri Gribenko | 97555a1 | 2012-12-15 21:10:51 +0000 | [diff] [blame] | 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>`. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 62 | |
| 63 | Note that those options must reach clang's cc1 process. There are two |
| 64 | ways to do so: |
| 65 | |
Dmitri Gribenko | 97555a1 | 2012-12-15 21:10:51 +0000 | [diff] [blame] | 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`. |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 72 | |
Dmitri Gribenko | 97555a1 | 2012-12-15 21:10:51 +0000 | [diff] [blame] | 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: |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 76 | |
Dmitri Gribenko | 97555a1 | 2012-12-15 21:10:51 +0000 | [diff] [blame] | 77 | .. code-block:: console |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 78 | |
Dmitri Gribenko | 97555a1 | 2012-12-15 21:10:51 +0000 | [diff] [blame] | 79 | $ export BD=/path/to/build/directory |
| 80 | $ (cd $BD && make PrintFunctionNames ) |
| 81 | $ clang++ -D_GNU_SOURCE -D_DEBUG -D__STDC_CONSTANT_MACROS \ |
Sean Silva | 93ca021 | 2012-12-13 01:10:46 +0000 | [diff] [blame] | 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>`_ |
Dmitri Gribenko | 97555a1 | 2012-12-15 21:10:51 +0000 | [diff] [blame] | 90 | |