|
150
|
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 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 <https://github.com/llvm/llvm-project/blob/master/clang/examples/PrintFunctionNames/PrintFunctionNames.cpp>`_.
|
|
|
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 <https://github.com/llvm/llvm-project/blob/master/clang/examples/PrintFunctionNames/README.txt>`_
|
|
|
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 }
|
