]>
Commit | Line | Data |
---|---|---|
a5544970 | 1 | @c Copyright (C) 2009-2019 Free Software Foundation, Inc. |
68a607d8 DN |
2 | @c Free Software Foundation, Inc. |
3 | @c This is part of the GCC manual. | |
4 | @c For copying conditions, see the file gcc.texi. | |
5 | ||
6 | @node Plugins | |
7 | @chapter Plugins | |
8 | @cindex Plugins | |
9 | ||
da3831fd GP |
10 | GCC plugins are loadable modules that provide extra features to the |
11 | compiler. Like GCC itself they can be distributed in source and | |
12 | binary forms. | |
548e68fc JL |
13 | |
14 | GCC plugins provide developers with a rich subset of | |
15 | the GCC API to allow them to extend GCC as they see fit. | |
16 | Whether it is writing an additional optimization pass, | |
17 | transforming code, or analyzing information, plugins | |
18 | can be quite useful. | |
19 | ||
20 | @menu | |
21 | * Plugins loading:: How can we load plugins. | |
22 | * Plugin API:: The APIs for plugins. | |
23 | * Plugins pass:: How a plugin interact with the pass manager. | |
24 | * Plugins GC:: How a plugin Interact with GCC Garbage Collector. | |
25 | * Plugins description:: Giving information about a plugin itself. | |
26 | * Plugins attr:: Registering custom attributes or pragmas. | |
27 | * Plugins recording:: Recording information about pass execution. | |
28 | * Plugins gate:: Controlling which passes are being run. | |
29 | * Plugins tracking:: Keeping track of available passes. | |
30 | * Plugins building:: How can we build a plugin. | |
31 | @end menu | |
32 | ||
33 | @node Plugins loading | |
68a607d8 DN |
34 | @section Loading Plugins |
35 | ||
ae2392a9 | 36 | Plugins are supported on platforms that support @option{-ldl |
8c7dbea9 BK |
37 | -rdynamic} as well as Windows/MinGW. They are loaded by the compiler |
38 | using @code{dlopen} or equivalent and invoked at pre-determined | |
39 | locations in the compilation process. | |
68a607d8 | 40 | |
ff2ce160 | 41 | Plugins are loaded with |
68a607d8 | 42 | |
8c7dbea9 | 43 | @option{-fplugin=/path/to/@var{name}.@var{ext}} @option{-fplugin-arg-@var{name}-@var{key1}[=@var{value1}]} |
68a607d8 | 44 | |
8c7dbea9 BK |
45 | Where @var{name} is the plugin name and @var{ext} is the platform-specific |
46 | dynamic library extension. It should be @code{dll} on Windows/MinGW, | |
47 | @code{dylib} on Darwin/Mac OS X, and @code{so} on all other platforms. | |
68a607d8 DN |
48 | The plugin arguments are parsed by GCC and passed to respective |
49 | plugins as key-value pairs. Multiple plugins can be invoked by | |
50 | specifying multiple @option{-fplugin} arguments. | |
51 | ||
4adbd5dd | 52 | A plugin can be simply given by its short name (no dots or |
917e11d7 RW |
53 | slashes). When simply passing @option{-fplugin=@var{name}}, the plugin is |
54 | loaded from the @file{plugin} directory, so @option{-fplugin=@var{name}} is | |
8c7dbea9 | 55 | the same as @option{-fplugin=`gcc -print-file-name=plugin`/@var{name}.@var{ext}}, |
4adbd5dd | 56 | using backquote shell syntax to query the @file{plugin} directory. |
68a607d8 | 57 | |
548e68fc | 58 | @node Plugin API |
68a607d8 DN |
59 | @section Plugin API |
60 | ||
61 | Plugins are activated by the compiler at specific events as defined in | |
62 | @file{gcc-plugin.h}. For each event of interest, the plugin should | |
63 | call @code{register_callback} specifying the name of the event and | |
64 | address of the callback function that will handle that event. | |
65 | ||
3e17e31d RAE |
66 | The header @file{gcc-plugin.h} must be the first gcc header to be included. |
67 | ||
fca5bb5c DN |
68 | @subsection Plugin license check |
69 | ||
70 | Every plugin should define the global symbol @code{plugin_is_GPL_compatible} | |
71 | to assert that it has been licensed under a GPL-compatible license. | |
72 | If this symbol does not exist, the compiler will emit a fatal error | |
73 | and exit with the error message: | |
74 | ||
75 | @smallexample | |
917e11d7 RW |
76 | fatal error: plugin @var{name} is not licensed under a GPL-compatible license |
77 | @var{name}: undefined symbol: plugin_is_GPL_compatible | |
fca5bb5c DN |
78 | compilation terminated |
79 | @end smallexample | |
80 | ||
2d7f5f9b JR |
81 | The declared type of the symbol should be int, to match a forward declaration |
82 | in @file{gcc-plugin.h} that suppresses C++ mangling. It does not need to be in | |
83 | any allocated section, though. The compiler merely asserts that | |
84 | the symbol exists in the global scope. Something like this is enough: | |
fca5bb5c DN |
85 | |
86 | @smallexample | |
87 | int plugin_is_GPL_compatible; | |
88 | @end smallexample | |
89 | ||
68a607d8 DN |
90 | @subsection Plugin initialization |
91 | ||
92 | Every plugin should export a function called @code{plugin_init} that | |
93 | is called right after the plugin is loaded. This function is | |
94 | responsible for registering all the callbacks required by the plugin | |
95 | and do any other required initialization. | |
96 | ||
97 | This function is called from @code{compile_file} right before invoking | |
98 | the parser. The arguments to @code{plugin_init} are: | |
99 | ||
100 | @itemize @bullet | |
9fefa0aa TG |
101 | @item @code{plugin_info}: Plugin invocation information. |
102 | @item @code{version}: GCC version. | |
68a607d8 DN |
103 | @end itemize |
104 | ||
9fefa0aa TG |
105 | The @code{plugin_info} struct is defined as follows: |
106 | ||
107 | @smallexample | |
108 | struct plugin_name_args | |
109 | @{ | |
110 | char *base_name; /* Short name of the plugin | |
111 | (filename without .so suffix). */ | |
112 | const char *full_name; /* Path to the plugin as specified with | |
113 | -fplugin=. */ | |
114 | int argc; /* Number of arguments specified with | |
115 | -fplugin-arg-.... */ | |
116 | struct plugin_argument *argv; /* Array of ARGC key-value pairs. */ | |
117 | const char *version; /* Version string provided by plugin. */ | |
118 | const char *help; /* Help string provided by plugin. */ | |
119 | @} | |
120 | @end smallexample | |
121 | ||
68a607d8 DN |
122 | If initialization fails, @code{plugin_init} must return a non-zero |
123 | value. Otherwise, it should return 0. | |
124 | ||
ae2392a9 BS |
125 | The version of the GCC compiler loading the plugin is described by the |
126 | following structure: | |
127 | ||
128 | @smallexample | |
129 | struct plugin_gcc_version | |
130 | @{ | |
131 | const char *basever; | |
132 | const char *datestamp; | |
133 | const char *devphase; | |
134 | const char *revision; | |
135 | const char *configuration_arguments; | |
136 | @}; | |
137 | @end smallexample | |
138 | ||
139 | The function @code{plugin_default_version_check} takes two pointers to | |
140 | such structure and compare them field by field. It can be used by the | |
141 | plugin's @code{plugin_init} function. | |
142 | ||
e4d5031c RE |
143 | The version of GCC used to compile the plugin can be found in the symbol |
144 | @code{gcc_version} defined in the header @file{plugin-version.h}. The | |
145 | recommended version check to perform looks like | |
146 | ||
147 | @smallexample | |
148 | #include "plugin-version.h" | |
149 | ... | |
150 | ||
151 | int | |
152 | plugin_init (struct plugin_name_args *plugin_info, | |
153 | struct plugin_gcc_version *version) | |
154 | @{ | |
155 | if (!plugin_default_version_check (version, &gcc_version)) | |
156 | return 1; | |
157 | ||
158 | @} | |
159 | @end smallexample | |
160 | ||
161 | but you can also check the individual fields if you want a less strict check. | |
ae2392a9 | 162 | |
68a607d8 DN |
163 | @subsection Plugin callbacks |
164 | ||
165 | Callback functions have the following prototype: | |
166 | ||
167 | @smallexample | |
168 | /* The prototype for a plugin callback function. | |
169 | gcc_data - event-specific data provided by GCC | |
170 | user_data - plugin-specific data provided by the plug-in. */ | |
171 | typedef void (*plugin_callback_func)(void *gcc_data, void *user_data); | |
172 | @end smallexample | |
173 | ||
174 | Callbacks can be invoked at the following pre-determined events: | |
175 | ||
176 | ||
177 | @smallexample | |
178 | enum plugin_event | |
179 | @{ | |
ea5b45b6 AT |
180 | PLUGIN_START_PARSE_FUNCTION, /* Called before parsing the body of a function. */ |
181 | PLUGIN_FINISH_PARSE_FUNCTION, /* After finishing parsing a function. */ | |
68a607d8 DN |
182 | PLUGIN_PASS_MANAGER_SETUP, /* To hook into pass manager. */ |
183 | PLUGIN_FINISH_TYPE, /* After finishing parsing a type. */ | |
4309e92c | 184 | PLUGIN_FINISH_DECL, /* After finishing parsing a declaration. */ |
68a607d8 | 185 | PLUGIN_FINISH_UNIT, /* Useful for summary processing. */ |
56c51155 | 186 | PLUGIN_PRE_GENERICIZE, /* Allows to see low level AST in C and C++ frontends. */ |
68a607d8 | 187 | PLUGIN_FINISH, /* Called before GCC exits. */ |
ae2392a9 | 188 | PLUGIN_INFO, /* Information about the plugin. */ |
02a9370c RW |
189 | PLUGIN_GGC_START, /* Called at start of GCC Garbage Collection. */ |
190 | PLUGIN_GGC_MARKING, /* Extend the GGC marking. */ | |
191 | PLUGIN_GGC_END, /* Called at end of GGC. */ | |
192 | PLUGIN_REGISTER_GGC_ROOTS, /* Register an extra GGC root table. */ | |
d1c8e08a | 193 | PLUGIN_ATTRIBUTES, /* Called during attribute registration */ |
78bf7bd0 | 194 | PLUGIN_START_UNIT, /* Called before processing a translation unit. */ |
02a9370c | 195 | PLUGIN_PRAGMAS, /* Called during pragma registration. */ |
090fa0ab GF |
196 | /* Called before first pass from all_passes. */ |
197 | PLUGIN_ALL_PASSES_START, | |
198 | /* Called after last pass from all_passes. */ | |
199 | PLUGIN_ALL_PASSES_END, | |
200 | /* Called before first ipa pass. */ | |
201 | PLUGIN_ALL_IPA_PASSES_START, | |
202 | /* Called after last ipa pass. */ | |
203 | PLUGIN_ALL_IPA_PASSES_END, | |
204 | /* Allows to override pass gate decision for current_pass. */ | |
205 | PLUGIN_OVERRIDE_GATE, | |
206 | /* Called before executing a pass. */ | |
207 | PLUGIN_PASS_EXECUTION, | |
208 | /* Called before executing subpasses of a GIMPLE_PASS in | |
209 | execute_ipa_pass_list. */ | |
210 | PLUGIN_EARLY_GIMPLE_PASSES_START, | |
211 | /* Called after executing subpasses of a GIMPLE_PASS in | |
212 | execute_ipa_pass_list. */ | |
213 | PLUGIN_EARLY_GIMPLE_PASSES_END, | |
214 | /* Called when a pass is first instantiated. */ | |
215 | PLUGIN_NEW_PASS, | |
b318e404 BS |
216 | /* Called when a file is #include-d or given via the #line directive. |
217 | This could happen many times. The event data is the included file path, | |
218 | as a const char* pointer. */ | |
219 | PLUGIN_INCLUDE_FILE, | |
090fa0ab GF |
220 | |
221 | PLUGIN_EVENT_FIRST_DYNAMIC /* Dummy event used for indexing callback | |
68a607d8 DN |
222 | array. */ |
223 | @}; | |
224 | @end smallexample | |
225 | ||
090fa0ab GF |
226 | In addition, plugins can also look up the enumerator of a named event, |
227 | and / or generate new events dynamically, by calling the function | |
228 | @code{get_named_event_id}. | |
ae2392a9 BS |
229 | |
230 | To register a callback, the plugin calls @code{register_callback} with | |
231 | the arguments: | |
68a607d8 DN |
232 | |
233 | @itemize | |
234 | @item @code{char *name}: Plugin name. | |
090fa0ab | 235 | @item @code{int event}: The event code. |
68a607d8 DN |
236 | @item @code{plugin_callback_func callback}: The function that handles @code{event}. |
237 | @item @code{void *user_data}: Pointer to plugin-specific data. | |
238 | @end itemize | |
239 | ||
63f5d5b8 TS |
240 | For the @i{PLUGIN_PASS_MANAGER_SETUP}, @i{PLUGIN_INFO}, and |
241 | @i{PLUGIN_REGISTER_GGC_ROOTS} pseudo-events the @code{callback} should be null, | |
242 | and the @code{user_data} is specific. | |
b318e404 BS |
243 | |
244 | When the @i{PLUGIN_PRAGMAS} event is triggered (with a null pointer as | |
245 | data from GCC), plugins may register their own pragmas. Notice that | |
246 | pragmas are not available from @file{lto1}, so plugins used with | |
247 | @code{-flto} option to GCC during link-time optimization cannot use | |
248 | pragmas and do not even see functions like @code{c_register_pragma} or | |
249 | @code{pragma_lex}. | |
250 | ||
251 | The @i{PLUGIN_INCLUDE_FILE} event, with a @code{const char*} file path as | |
252 | GCC data, is triggered for processing of @code{#include} or | |
253 | @code{#line} directives. | |
254 | ||
255 | The @i{PLUGIN_FINISH} event is the last time that plugins can call GCC | |
256 | functions, notably emit diagnostics with @code{warning}, @code{error} | |
257 | etc. | |
68a607d8 | 258 | |
7ac8318c | 259 | |
548e68fc | 260 | @node Plugins pass |
68a607d8 DN |
261 | @section Interacting with the pass manager |
262 | ||
263 | There needs to be a way to add/reorder/remove passes dynamically. This | |
264 | is useful for both analysis plugins (plugging in after a certain pass | |
265 | such as CFG or an IPA pass) and optimization plugins. | |
266 | ||
267 | Basic support for inserting new passes or replacing existing passes is | |
268 | provided. A plugin registers a new pass with GCC by calling | |
269 | @code{register_callback} with the @code{PLUGIN_PASS_MANAGER_SETUP} | |
8fc7e474 | 270 | event and a pointer to a @code{struct register_pass_info} object defined as follows |
68a607d8 DN |
271 | |
272 | @smallexample | |
273 | enum pass_positioning_ops | |
274 | @{ | |
275 | PASS_POS_INSERT_AFTER, // Insert after the reference pass. | |
276 | PASS_POS_INSERT_BEFORE, // Insert before the reference pass. | |
277 | PASS_POS_REPLACE // Replace the reference pass. | |
278 | @}; | |
279 | ||
8fc7e474 | 280 | struct register_pass_info |
68a607d8 DN |
281 | @{ |
282 | struct opt_pass *pass; /* New pass provided by the plugin. */ | |
283 | const char *reference_pass_name; /* Name of the reference pass for hooking | |
284 | up the new pass. */ | |
285 | int ref_pass_instance_number; /* Insert the pass at the specified | |
286 | instance number of the reference pass. */ | |
287 | /* Do it for every instance if it is 0. */ | |
288 | enum pass_positioning_ops pos_op; /* how to insert the new pass. */ | |
289 | @}; | |
290 | ||
291 | ||
292 | /* Sample plugin code that registers a new pass. */ | |
293 | int | |
9fefa0aa TG |
294 | plugin_init (struct plugin_name_args *plugin_info, |
295 | struct plugin_gcc_version *version) | |
68a607d8 | 296 | @{ |
8fc7e474 | 297 | struct register_pass_info pass_info; |
68a607d8 DN |
298 | |
299 | ... | |
300 | ||
301 | /* Code to fill in the pass_info object with new pass information. */ | |
302 | ||
303 | ... | |
304 | ||
305 | /* Register the new pass. */ | |
9fefa0aa | 306 | register_callback (plugin_info->base_name, PLUGIN_PASS_MANAGER_SETUP, NULL, &pass_info); |
68a607d8 DN |
307 | |
308 | ... | |
309 | @} | |
310 | @end smallexample | |
ae2392a9 BS |
311 | |
312 | ||
548e68fc | 313 | @node Plugins GC |
ff2ce160 | 314 | @section Interacting with the GCC Garbage Collector |
ae2392a9 BS |
315 | |
316 | Some plugins may want to be informed when GGC (the GCC Garbage | |
317 | Collector) is running. They can register callbacks for the | |
318 | @code{PLUGIN_GGC_START} and @code{PLUGIN_GGC_END} events (for which | |
319 | the callback is called with a null @code{gcc_data}) to be notified of | |
320 | the start or end of the GCC garbage collection. | |
321 | ||
322 | Some plugins may need to have GGC mark additional data. This can be | |
323 | done by registering a callback (called with a null @code{gcc_data}) | |
324 | for the @code{PLUGIN_GGC_MARKING} event. Such callbacks can call the | |
073a8998 | 325 | @code{ggc_set_mark} routine, preferably through the @code{ggc_mark} macro |
bd117bb6 | 326 | (and conversely, these routines should usually not be used in plugins |
63f5d5b8 TS |
327 | outside of the @code{PLUGIN_GGC_MARKING} event). Plugins that wish to hold |
328 | weak references to gc data may also use this event to drop weak references when | |
329 | the object is about to be collected. The @code{ggc_marked_p} function can be | |
330 | used to tell if an object is marked, or is about to be collected. The | |
331 | @code{gt_clear_cache} overloads which some types define may also be of use in | |
332 | managing weak references. | |
ae2392a9 | 333 | |
630ba2fd | 334 | Some plugins may need to add extra GGC root tables, e.g.@: to handle their own |
32c9b4e9 DS |
335 | @code{GTY}-ed data. This can be done with the @code{PLUGIN_REGISTER_GGC_ROOTS} |
336 | pseudo-event with a null callback and the extra root table (of type @code{struct | |
63f5d5b8 TS |
337 | ggc_root_tab*}) as @code{user_data}. Running the |
338 | @code{gengtype -p @var{source-dir} @var{file-list} @var{plugin*.c} ...} | |
339 | utility generates these extra root tables. | |
ae2392a9 BS |
340 | |
341 | You should understand the details of memory management inside GCC | |
63f5d5b8 | 342 | before using @code{PLUGIN_GGC_MARKING} or @code{PLUGIN_REGISTER_GGC_ROOTS}. |
ae2392a9 BS |
343 | |
344 | ||
548e68fc | 345 | @node Plugins description |
ae2392a9 BS |
346 | @section Giving information about a plugin |
347 | ||
348 | A plugin should give some information to the user about itself. This | |
349 | uses the following structure: | |
350 | ||
351 | @smallexample | |
352 | struct plugin_info | |
353 | @{ | |
354 | const char *version; | |
355 | const char *help; | |
356 | @}; | |
357 | @end smallexample | |
358 | ||
359 | Such a structure is passed as the @code{user_data} by the plugin's | |
360 | init routine using @code{register_callback} with the | |
361 | @code{PLUGIN_INFO} pseudo-event and a null callback. | |
362 | ||
548e68fc | 363 | @node Plugins attr |
110532c8 | 364 | @section Registering custom attributes or pragmas |
d1c8e08a | 365 | |
110532c8 BS |
366 | For analysis (or other) purposes it is useful to be able to add custom |
367 | attributes or pragmas. | |
d1c8e08a TG |
368 | |
369 | The @code{PLUGIN_ATTRIBUTES} callback is called during attribute | |
370 | registration. Use the @code{register_attribute} function to register | |
371 | custom attributes. | |
372 | ||
373 | @smallexample | |
374 | /* Attribute handler callback */ | |
375 | static tree | |
376 | handle_user_attribute (tree *node, tree name, tree args, | |
73b8bfe1 | 377 | int flags, bool *no_add_attrs) |
d1c8e08a TG |
378 | @{ |
379 | return NULL_TREE; | |
380 | @} | |
381 | ||
382 | /* Attribute definition */ | |
383 | static struct attribute_spec user_attr = | |
4849deb1 | 384 | @{ "user", 1, 1, false, false, false, false, handle_user_attribute, NULL @}; |
d1c8e08a TG |
385 | |
386 | /* Plugin callback called during attribute registration. | |
387 | Registered with register_callback (plugin_name, PLUGIN_ATTRIBUTES, register_attributes, NULL) | |
388 | */ | |
ff2ce160 | 389 | static void |
d1c8e08a TG |
390 | register_attributes (void *event_data, void *data) |
391 | @{ | |
392 | warning (0, G_("Callback to register attributes")); | |
393 | register_attribute (&user_attr); | |
394 | @} | |
395 | ||
396 | @end smallexample | |
07ae5620 BS |
397 | |
398 | ||
b318e404 BS |
399 | The @i{PLUGIN_PRAGMAS} callback is called once during pragmas |
400 | registration. Use the @code{c_register_pragma}, | |
401 | @code{c_register_pragma_with_data}, | |
402 | @code{c_register_pragma_with_expansion}, | |
403 | @code{c_register_pragma_with_expansion_and_data} functions to register | |
404 | custom pragmas and their handlers (which often want to call | |
405 | @code{pragma_lex}) from @file{c-family/c-pragma.h}. | |
110532c8 BS |
406 | |
407 | @smallexample | |
408 | /* Plugin callback called during pragmas registration. Registered with | |
409 | register_callback (plugin_name, PLUGIN_PRAGMAS, | |
410 | register_my_pragma, NULL); | |
411 | */ | |
ff2ce160 MS |
412 | static void |
413 | register_my_pragma (void *event_data, void *data) | |
110532c8 BS |
414 | @{ |
415 | warning (0, G_("Callback to register pragmas")); | |
416 | c_register_pragma ("GCCPLUGIN", "sayhello", handle_pragma_sayhello); | |
417 | @} | |
418 | @end smallexample | |
419 | ||
420 | It is suggested to pass @code{"GCCPLUGIN"} (or a short name identifying | |
ff2ce160 | 421 | your plugin) as the ``space'' argument of your pragma. |
110532c8 | 422 | |
b318e404 BS |
423 | Pragmas registered with @code{c_register_pragma_with_expansion} or |
424 | @code{c_register_pragma_with_expansion_and_data} support | |
425 | preprocessor expansions. For example: | |
426 | ||
427 | @smallexample | |
428 | #define NUMBER 10 | |
429 | #pragma GCCPLUGIN foothreshold (NUMBER) | |
430 | @end smallexample | |
110532c8 | 431 | |
548e68fc | 432 | @node Plugins recording |
090fa0ab GF |
433 | @section Recording information about pass execution |
434 | ||
435 | The event PLUGIN_PASS_EXECUTION passes the pointer to the executed pass | |
436 | (the same as current_pass) as @code{gcc_data} to the callback. You can also | |
437 | inspect cfun to find out about which function this pass is executed for. | |
438 | Note that this event will only be invoked if the gate check (if | |
439 | applicable, modified by PLUGIN_OVERRIDE_GATE) succeeds. | |
440 | You can use other hooks, like @code{PLUGIN_ALL_PASSES_START}, | |
441 | @code{PLUGIN_ALL_PASSES_END}, @code{PLUGIN_ALL_IPA_PASSES_START}, | |
442 | @code{PLUGIN_ALL_IPA_PASSES_END}, @code{PLUGIN_EARLY_GIMPLE_PASSES_START}, | |
443 | and/or @code{PLUGIN_EARLY_GIMPLE_PASSES_END} to manipulate global state | |
444 | in your plugin(s) in order to get context for the pass execution. | |
445 | ||
446 | ||
548e68fc | 447 | @node Plugins gate |
090fa0ab GF |
448 | @section Controlling which passes are being run |
449 | ||
450 | After the original gate function for a pass is called, its result | |
451 | - the gate status - is stored as an integer. | |
452 | Then the event @code{PLUGIN_OVERRIDE_GATE} is invoked, with a pointer | |
453 | to the gate status in the @code{gcc_data} parameter to the callback function. | |
454 | A nonzero value of the gate status means that the pass is to be executed. | |
455 | You can both read and write the gate status via the passed pointer. | |
456 | ||
457 | ||
548e68fc | 458 | @node Plugins tracking |
090fa0ab GF |
459 | @section Keeping track of available passes |
460 | ||
461 | When your plugin is loaded, you can inspect the various | |
462 | pass lists to determine what passes are available. However, other | |
463 | plugins might add new passes. Also, future changes to GCC might cause | |
464 | generic passes to be added after plugin loading. | |
465 | When a pass is first added to one of the pass lists, the event | |
466 | @code{PLUGIN_NEW_PASS} is invoked, with the callback parameter | |
467 | @code{gcc_data} pointing to the new pass. | |
468 | ||
469 | ||
548e68fc | 470 | @node Plugins building |
07ae5620 BS |
471 | @section Building GCC plugins |
472 | ||
473 | If plugins are enabled, GCC installs the headers needed to build a | |
630ba2fd | 474 | plugin (somewhere in the installation tree, e.g.@: under |
07ae5620 BS |
475 | @file{/usr/local}). In particular a @file{plugin/include} directory |
476 | is installed, containing all the header files needed to build plugins. | |
477 | ||
478 | On most systems, you can query this @code{plugin} directory by | |
479 | invoking @command{gcc -print-file-name=plugin} (replace if needed | |
480 | @command{gcc} with the appropriate program path). | |
481 | ||
4adbd5dd MK |
482 | Inside plugins, this @code{plugin} directory name can be queried by |
483 | calling @code{default_plugin_dir_name ()}. | |
484 | ||
bf588455 BS |
485 | Plugins may know, when they are compiled, the GCC version for which |
486 | @file{plugin-version.h} is provided. The constant macros | |
487 | @code{GCCPLUGIN_VERSION_MAJOR}, @code{GCCPLUGIN_VERSION_MINOR}, | |
488 | @code{GCCPLUGIN_VERSION_PATCHLEVEL}, @code{GCCPLUGIN_VERSION} are | |
489 | integer numbers, so a plugin could ensure it is built for GCC 4.7 with | |
490 | @smallexample | |
491 | #if GCCPLUGIN_VERSION != 4007 | |
492 | #error this GCC plugin is for GCC 4.7 | |
493 | #endif | |
494 | @end smallexample | |
495 | ||
07ae5620 BS |
496 | The following GNU Makefile excerpt shows how to build a simple plugin: |
497 | ||
498 | @smallexample | |
a984e92e JY |
499 | HOST_GCC=g++ |
500 | TARGET_GCC=gcc | |
501 | PLUGIN_SOURCE_FILES= plugin1.c plugin2.cc | |
502 | GCCPLUGINS_DIR:= $(shell $(TARGET_GCC) -print-file-name=plugin) | |
503 | CXXFLAGS+= -I$(GCCPLUGINS_DIR)/include -fPIC -fno-rtti -O2 | |
504 | ||
505 | plugin.so: $(PLUGIN_SOURCE_FILES) | |
506 | $(HOST_GCC) -shared $(CXXFLAGS) $^ -o $@@ | |
07ae5620 BS |
507 | @end smallexample |
508 | ||
a984e92e JY |
509 | A single source file plugin may be built with @code{g++ -I`gcc |
510 | -print-file-name=plugin`/include -fPIC -shared -fno-rtti -O2 plugin.c -o | |
07ae5620 BS |
511 | plugin.so}, using backquote shell syntax to query the @file{plugin} |
512 | directory. | |
513 | ||
8c7dbea9 BK |
514 | Plugin support on Windows/MinGW has a number of limitations and |
515 | additional requirements. When building a plugin on Windows we have to | |
516 | link an import library for the corresponding backend executable, for | |
517 | example, @file{cc1.exe}, @file{cc1plus.exe}, etc., in order to gain | |
518 | access to the symbols provided by GCC. This means that on Windows a | |
519 | plugin is language-specific, for example, for C, C++, etc. If you wish | |
520 | to use your plugin with multiple languages, then you will need to | |
521 | build multiple plugin libraries and either instruct your users on how | |
522 | to load the correct version or provide a compiler wrapper that does | |
523 | this automatically. | |
524 | ||
525 | Additionally, on Windows the plugin library has to export the | |
526 | @code{plugin_is_GPL_compatible} and @code{plugin_init} symbols. If you | |
527 | do not wish to modify the source code of your plugin, then you can use | |
528 | the @option{-Wl,--export-all-symbols} option or provide a suitable DEF | |
529 | file. Alternatively, you can export just these two symbols by decorating | |
530 | them with @code{__declspec(dllexport)}, for example: | |
531 | ||
532 | @smallexample | |
533 | #ifdef _WIN32 | |
534 | __declspec(dllexport) | |
535 | #endif | |
536 | int plugin_is_GPL_compatible; | |
537 | ||
538 | #ifdef _WIN32 | |
539 | __declspec(dllexport) | |
540 | #endif | |
541 | int plugin_init (plugin_name_args *, plugin_gcc_version *) | |
542 | @end smallexample | |
543 | ||
544 | The import libraries are installed into the @code{plugin} directory | |
545 | and their names are derived by appending the @code{.a} extension to | |
546 | the backend executable names, for example, @file{cc1.exe.a}, | |
547 | @file{cc1plus.exe.a}, etc. The following command line shows how to | |
548 | build the single source file plugin on Windows to be used with the C++ | |
549 | compiler: | |
550 | ||
551 | @smallexample | |
552 | g++ -I`gcc -print-file-name=plugin`/include -shared -Wl,--export-all-symbols \ | |
553 | -o plugin.dll plugin.c `gcc -print-file-name=plugin`/cc1plus.exe.a | |
554 | @end smallexample | |
555 | ||
44762055 BS |
556 | When a plugin needs to use @command{gengtype}, be sure that both |
557 | @file{gengtype} and @file{gtype.state} have the same version as the | |
558 | GCC for which the plugin is built. |