ClangPlugins.rst source code [clang_source

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	<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	}
131

Clang Project