| 1 |
@c Copyright (C) 2009-2023 Free Software Foundation, Inc. |
| 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 |
|
| 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. |
| 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 |
| 34 |
@section Loading Plugins |
| 35 |
|
| 36 |
Plugins are supported on platforms that support @option{-ldl |
| 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. |
| 40 |
|
| 41 |
Plugins are loaded with |
| 42 |
|
| 43 |
@option{-fplugin=/path/to/@var{name}.@var{ext}} @option{-fplugin-arg-@var{name}-@var{key1}[=@var{value1}]} |
| 44 |
|
| 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. |
| 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 |
|
| 52 |
A plugin can be simply given by its short name (no dots or |
| 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 |
| 55 |
the same as @option{-fplugin=`gcc -print-file-name=plugin`/@var{name}.@var{ext}}, |
| 56 |
using backquote shell syntax to query the @file{plugin} directory. |
| 57 |
|
| 58 |
@node Plugin API |
| 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 |
|
| 66 |
The header @file{gcc-plugin.h} must be the first gcc header to be included. |
| 67 |
|
| 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 |
| 76 |
fatal error: plugin @var{name} is not licensed under a GPL-compatible license |
| 77 |
@var{name}: undefined symbol: plugin_is_GPL_compatible |
| 78 |
compilation terminated |
| 79 |
@end smallexample |
| 80 |
|
| 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: |
| 85 |
|
| 86 |
@smallexample |
| 87 |
int plugin_is_GPL_compatible; |
| 88 |
@end smallexample |
| 89 |
|
| 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 |
| 101 |
@item @code{plugin_info}: Plugin invocation information. |
| 102 |
@item @code{version}: GCC version. |
| 103 |
@end itemize |
| 104 |
|
| 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 |
|
| 122 |
If initialization fails, @code{plugin_init} must return a non-zero |
| 123 |
value. Otherwise, it should return 0. |
| 124 |
|
| 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 |
|
| 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. |
| 162 |
|
| 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 |
@{ |
| 180 |
PLUGIN_START_PARSE_FUNCTION, /* Called before parsing the body of a function. */ |
| 181 |
PLUGIN_FINISH_PARSE_FUNCTION, /* After finishing parsing a function. */ |
| 182 |
PLUGIN_PASS_MANAGER_SETUP, /* To hook into pass manager. */ |
| 183 |
PLUGIN_FINISH_TYPE, /* After finishing parsing a type. */ |
| 184 |
PLUGIN_FINISH_DECL, /* After finishing parsing a declaration. */ |
| 185 |
PLUGIN_FINISH_UNIT, /* Useful for summary processing. */ |
| 186 |
PLUGIN_PRE_GENERICIZE, /* Allows to see low level AST in C and C++ frontends. */ |
| 187 |
PLUGIN_FINISH, /* Called before GCC exits. */ |
| 188 |
PLUGIN_INFO, /* Information about the plugin. */ |
| 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. */ |
| 193 |
PLUGIN_ATTRIBUTES, /* Called during attribute registration */ |
| 194 |
PLUGIN_START_UNIT, /* Called before processing a translation unit. */ |
| 195 |
PLUGIN_PRAGMAS, /* Called during pragma registration. */ |
| 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, |
| 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, |
| 220 |
|
| 221 |
/* Called when -fanalyzer starts. The event data is an |
| 222 |
ana::plugin_analyzer_init_iface *. */ |
| 223 |
PLUGIN_ANALYZER_INIT, |
| 224 |
|
| 225 |
PLUGIN_EVENT_FIRST_DYNAMIC /* Dummy event used for indexing callback |
| 226 |
array. */ |
| 227 |
@}; |
| 228 |
@end smallexample |
| 229 |
|
| 230 |
In addition, plugins can also look up the enumerator of a named event, |
| 231 |
and / or generate new events dynamically, by calling the function |
| 232 |
@code{get_named_event_id}. |
| 233 |
|
| 234 |
To register a callback, the plugin calls @code{register_callback} with |
| 235 |
the arguments: |
| 236 |
|
| 237 |
@itemize |
| 238 |
@item @code{char *name}: Plugin name. |
| 239 |
@item @code{int event}: The event code. |
| 240 |
@item @code{plugin_callback_func callback}: The function that handles @code{event}. |
| 241 |
@item @code{void *user_data}: Pointer to plugin-specific data. |
| 242 |
@end itemize |
| 243 |
|
| 244 |
For the @i{PLUGIN_PASS_MANAGER_SETUP}, @i{PLUGIN_INFO}, and |
| 245 |
@i{PLUGIN_REGISTER_GGC_ROOTS} pseudo-events the @code{callback} should be null, |
| 246 |
and the @code{user_data} is specific. |
| 247 |
|
| 248 |
When the @i{PLUGIN_PRAGMAS} event is triggered (with a null pointer as |
| 249 |
data from GCC), plugins may register their own pragmas. Notice that |
| 250 |
pragmas are not available from @file{lto1}, so plugins used with |
| 251 |
@code{-flto} option to GCC during link-time optimization cannot use |
| 252 |
pragmas and do not even see functions like @code{c_register_pragma} or |
| 253 |
@code{pragma_lex}. |
| 254 |
|
| 255 |
The @i{PLUGIN_INCLUDE_FILE} event, with a @code{const char*} file path as |
| 256 |
GCC data, is triggered for processing of @code{#include} or |
| 257 |
@code{#line} directives. |
| 258 |
|
| 259 |
The @i{PLUGIN_FINISH} event is the last time that plugins can call GCC |
| 260 |
functions, notably emit diagnostics with @code{warning}, @code{error} |
| 261 |
etc. |
| 262 |
|
| 263 |
|
| 264 |
@node Plugins pass |
| 265 |
@section Interacting with the pass manager |
| 266 |
|
| 267 |
There needs to be a way to add/reorder/remove passes dynamically. This |
| 268 |
is useful for both analysis plugins (plugging in after a certain pass |
| 269 |
such as CFG or an IPA pass) and optimization plugins. |
| 270 |
|
| 271 |
Basic support for inserting new passes or replacing existing passes is |
| 272 |
provided. A plugin registers a new pass with GCC by calling |
| 273 |
@code{register_callback} with the @code{PLUGIN_PASS_MANAGER_SETUP} |
| 274 |
event and a pointer to a @code{struct register_pass_info} object defined as follows |
| 275 |
|
| 276 |
@smallexample |
| 277 |
enum pass_positioning_ops |
| 278 |
@{ |
| 279 |
PASS_POS_INSERT_AFTER, // Insert after the reference pass. |
| 280 |
PASS_POS_INSERT_BEFORE, // Insert before the reference pass. |
| 281 |
PASS_POS_REPLACE // Replace the reference pass. |
| 282 |
@}; |
| 283 |
|
| 284 |
struct register_pass_info |
| 285 |
@{ |
| 286 |
struct opt_pass *pass; /* New pass provided by the plugin. */ |
| 287 |
const char *reference_pass_name; /* Name of the reference pass for hooking |
| 288 |
up the new pass. */ |
| 289 |
int ref_pass_instance_number; /* Insert the pass at the specified |
| 290 |
instance number of the reference pass. */ |
| 291 |
/* Do it for every instance if it is 0. */ |
| 292 |
enum pass_positioning_ops pos_op; /* how to insert the new pass. */ |
| 293 |
@}; |
| 294 |
|
| 295 |
|
| 296 |
/* Sample plugin code that registers a new pass. */ |
| 297 |
int |
| 298 |
plugin_init (struct plugin_name_args *plugin_info, |
| 299 |
struct plugin_gcc_version *version) |
| 300 |
@{ |
| 301 |
struct register_pass_info pass_info; |
| 302 |
|
| 303 |
... |
| 304 |
|
| 305 |
/* Code to fill in the pass_info object with new pass information. */ |
| 306 |
|
| 307 |
... |
| 308 |
|
| 309 |
/* Register the new pass. */ |
| 310 |
register_callback (plugin_info->base_name, PLUGIN_PASS_MANAGER_SETUP, NULL, &pass_info); |
| 311 |
|
| 312 |
... |
| 313 |
@} |
| 314 |
@end smallexample |
| 315 |
|
| 316 |
|
| 317 |
@node Plugins GC |
| 318 |
@section Interacting with the GCC Garbage Collector |
| 319 |
|
| 320 |
Some plugins may want to be informed when GGC (the GCC Garbage |
| 321 |
Collector) is running. They can register callbacks for the |
| 322 |
@code{PLUGIN_GGC_START} and @code{PLUGIN_GGC_END} events (for which |
| 323 |
the callback is called with a null @code{gcc_data}) to be notified of |
| 324 |
the start or end of the GCC garbage collection. |
| 325 |
|
| 326 |
Some plugins may need to have GGC mark additional data. This can be |
| 327 |
done by registering a callback (called with a null @code{gcc_data}) |
| 328 |
for the @code{PLUGIN_GGC_MARKING} event. Such callbacks can call the |
| 329 |
@code{ggc_set_mark} routine, preferably through the @code{ggc_mark} macro |
| 330 |
(and conversely, these routines should usually not be used in plugins |
| 331 |
outside of the @code{PLUGIN_GGC_MARKING} event). Plugins that wish to hold |
| 332 |
weak references to gc data may also use this event to drop weak references when |
| 333 |
the object is about to be collected. The @code{ggc_marked_p} function can be |
| 334 |
used to tell if an object is marked, or is about to be collected. The |
| 335 |
@code{gt_clear_cache} overloads which some types define may also be of use in |
| 336 |
managing weak references. |
| 337 |
|
| 338 |
Some plugins may need to add extra GGC root tables, e.g.@: to handle their own |
| 339 |
@code{GTY}-ed data. This can be done with the @code{PLUGIN_REGISTER_GGC_ROOTS} |
| 340 |
pseudo-event with a null callback and the extra root table (of type @code{struct |
| 341 |
ggc_root_tab*}) as @code{user_data}. Running the |
| 342 |
@code{gengtype -p @var{source-dir} @var{file-list} @var{plugin*.c} ...} |
| 343 |
utility generates these extra root tables. |
| 344 |
|
| 345 |
You should understand the details of memory management inside GCC |
| 346 |
before using @code{PLUGIN_GGC_MARKING} or @code{PLUGIN_REGISTER_GGC_ROOTS}. |
| 347 |
|
| 348 |
|
| 349 |
@node Plugins description |
| 350 |
@section Giving information about a plugin |
| 351 |
|
| 352 |
A plugin should give some information to the user about itself. This |
| 353 |
uses the following structure: |
| 354 |
|
| 355 |
@smallexample |
| 356 |
struct plugin_info |
| 357 |
@{ |
| 358 |
const char *version; |
| 359 |
const char *help; |
| 360 |
@}; |
| 361 |
@end smallexample |
| 362 |
|
| 363 |
Such a structure is passed as the @code{user_data} by the plugin's |
| 364 |
init routine using @code{register_callback} with the |
| 365 |
@code{PLUGIN_INFO} pseudo-event and a null callback. |
| 366 |
|
| 367 |
@node Plugins attr |
| 368 |
@section Registering custom attributes or pragmas |
| 369 |
|
| 370 |
For analysis (or other) purposes it is useful to be able to add custom |
| 371 |
attributes or pragmas. |
| 372 |
|
| 373 |
The @code{PLUGIN_ATTRIBUTES} callback is called during attribute |
| 374 |
registration. Use the @code{register_attribute} function to register |
| 375 |
custom attributes. |
| 376 |
|
| 377 |
@smallexample |
| 378 |
/* Attribute handler callback */ |
| 379 |
static tree |
| 380 |
handle_user_attribute (tree *node, tree name, tree args, |
| 381 |
int flags, bool *no_add_attrs) |
| 382 |
@{ |
| 383 |
return NULL_TREE; |
| 384 |
@} |
| 385 |
|
| 386 |
/* Attribute definition */ |
| 387 |
static struct attribute_spec user_attr = |
| 388 |
@{ "user", 1, 1, false, false, false, false, handle_user_attribute, NULL @}; |
| 389 |
|
| 390 |
/* Plugin callback called during attribute registration. |
| 391 |
Registered with register_callback (plugin_name, PLUGIN_ATTRIBUTES, register_attributes, NULL) |
| 392 |
*/ |
| 393 |
static void |
| 394 |
register_attributes (void *event_data, void *data) |
| 395 |
@{ |
| 396 |
warning (0, G_("Callback to register attributes")); |
| 397 |
register_attribute (&user_attr); |
| 398 |
@} |
| 399 |
|
| 400 |
@end smallexample |
| 401 |
|
| 402 |
|
| 403 |
The @i{PLUGIN_PRAGMAS} callback is called once during pragmas |
| 404 |
registration. Use the @code{c_register_pragma}, |
| 405 |
@code{c_register_pragma_with_data}, |
| 406 |
@code{c_register_pragma_with_expansion}, |
| 407 |
@code{c_register_pragma_with_expansion_and_data} functions to register |
| 408 |
custom pragmas and their handlers (which often want to call |
| 409 |
@code{pragma_lex}) from @file{c-family/c-pragma.h}. |
| 410 |
|
| 411 |
@smallexample |
| 412 |
/* Plugin callback called during pragmas registration. Registered with |
| 413 |
register_callback (plugin_name, PLUGIN_PRAGMAS, |
| 414 |
register_my_pragma, NULL); |
| 415 |
*/ |
| 416 |
static void |
| 417 |
register_my_pragma (void *event_data, void *data) |
| 418 |
@{ |
| 419 |
warning (0, G_("Callback to register pragmas")); |
| 420 |
c_register_pragma ("GCCPLUGIN", "sayhello", handle_pragma_sayhello); |
| 421 |
@} |
| 422 |
@end smallexample |
| 423 |
|
| 424 |
It is suggested to pass @code{"GCCPLUGIN"} (or a short name identifying |
| 425 |
your plugin) as the ``space'' argument of your pragma. |
| 426 |
|
| 427 |
Pragmas registered with @code{c_register_pragma_with_expansion} or |
| 428 |
@code{c_register_pragma_with_expansion_and_data} support |
| 429 |
preprocessor expansions. For example: |
| 430 |
|
| 431 |
@smallexample |
| 432 |
#define NUMBER 10 |
| 433 |
#pragma GCCPLUGIN foothreshold (NUMBER) |
| 434 |
@end smallexample |
| 435 |
|
| 436 |
@node Plugins recording |
| 437 |
@section Recording information about pass execution |
| 438 |
|
| 439 |
The event PLUGIN_PASS_EXECUTION passes the pointer to the executed pass |
| 440 |
(the same as current_pass) as @code{gcc_data} to the callback. You can also |
| 441 |
inspect cfun to find out about which function this pass is executed for. |
| 442 |
Note that this event will only be invoked if the gate check (if |
| 443 |
applicable, modified by PLUGIN_OVERRIDE_GATE) succeeds. |
| 444 |
You can use other hooks, like @code{PLUGIN_ALL_PASSES_START}, |
| 445 |
@code{PLUGIN_ALL_PASSES_END}, @code{PLUGIN_ALL_IPA_PASSES_START}, |
| 446 |
@code{PLUGIN_ALL_IPA_PASSES_END}, @code{PLUGIN_EARLY_GIMPLE_PASSES_START}, |
| 447 |
and/or @code{PLUGIN_EARLY_GIMPLE_PASSES_END} to manipulate global state |
| 448 |
in your plugin(s) in order to get context for the pass execution. |
| 449 |
|
| 450 |
|
| 451 |
@node Plugins gate |
| 452 |
@section Controlling which passes are being run |
| 453 |
|
| 454 |
After the original gate function for a pass is called, its result |
| 455 |
- the gate status - is stored as an integer. |
| 456 |
Then the event @code{PLUGIN_OVERRIDE_GATE} is invoked, with a pointer |
| 457 |
to the gate status in the @code{gcc_data} parameter to the callback function. |
| 458 |
A nonzero value of the gate status means that the pass is to be executed. |
| 459 |
You can both read and write the gate status via the passed pointer. |
| 460 |
|
| 461 |
|
| 462 |
@node Plugins tracking |
| 463 |
@section Keeping track of available passes |
| 464 |
|
| 465 |
When your plugin is loaded, you can inspect the various |
| 466 |
pass lists to determine what passes are available. However, other |
| 467 |
plugins might add new passes. Also, future changes to GCC might cause |
| 468 |
generic passes to be added after plugin loading. |
| 469 |
When a pass is first added to one of the pass lists, the event |
| 470 |
@code{PLUGIN_NEW_PASS} is invoked, with the callback parameter |
| 471 |
@code{gcc_data} pointing to the new pass. |
| 472 |
|
| 473 |
|
| 474 |
@node Plugins building |
| 475 |
@section Building GCC plugins |
| 476 |
|
| 477 |
If plugins are enabled, GCC installs the headers needed to build a |
| 478 |
plugin (somewhere in the installation tree, e.g.@: under |
| 479 |
@file{/usr/local}). In particular a @file{plugin/include} directory |
| 480 |
is installed, containing all the header files needed to build plugins. |
| 481 |
|
| 482 |
On most systems, you can query this @code{plugin} directory by |
| 483 |
invoking @command{gcc -print-file-name=plugin} (replace if needed |
| 484 |
@command{gcc} with the appropriate program path). |
| 485 |
|
| 486 |
Inside plugins, this @code{plugin} directory name can be queried by |
| 487 |
calling @code{default_plugin_dir_name ()}. |
| 488 |
|
| 489 |
Plugins may know, when they are compiled, the GCC version for which |
| 490 |
@file{plugin-version.h} is provided. The constant macros |
| 491 |
@code{GCCPLUGIN_VERSION_MAJOR}, @code{GCCPLUGIN_VERSION_MINOR}, |
| 492 |
@code{GCCPLUGIN_VERSION_PATCHLEVEL}, @code{GCCPLUGIN_VERSION} are |
| 493 |
integer numbers, so a plugin could ensure it is built for GCC 4.7 with |
| 494 |
@smallexample |
| 495 |
#if GCCPLUGIN_VERSION != 4007 |
| 496 |
#error this GCC plugin is for GCC 4.7 |
| 497 |
#endif |
| 498 |
@end smallexample |
| 499 |
|
| 500 |
The following GNU Makefile excerpt shows how to build a simple plugin: |
| 501 |
|
| 502 |
@smallexample |
| 503 |
HOST_GCC=g++ |
| 504 |
TARGET_GCC=gcc |
| 505 |
PLUGIN_SOURCE_FILES= plugin1.c plugin2.cc |
| 506 |
GCCPLUGINS_DIR:= $(shell $(TARGET_GCC) -print-file-name=plugin) |
| 507 |
CXXFLAGS+= -I$(GCCPLUGINS_DIR)/include -fPIC -fno-rtti -O2 |
| 508 |
|
| 509 |
plugin.so: $(PLUGIN_SOURCE_FILES) |
| 510 |
$(HOST_GCC) -shared $(CXXFLAGS) $^ -o $@@ |
| 511 |
@end smallexample |
| 512 |
|
| 513 |
A single source file plugin may be built with @code{g++ -I`gcc |
| 514 |
-print-file-name=plugin`/include -fPIC -shared -fno-rtti -O2 plugin.cc -o |
| 515 |
plugin.so}, using backquote shell syntax to query the @file{plugin} |
| 516 |
directory. |
| 517 |
|
| 518 |
Plugin support on Windows/MinGW has a number of limitations and |
| 519 |
additional requirements. When building a plugin on Windows we have to |
| 520 |
link an import library for the corresponding backend executable, for |
| 521 |
example, @file{cc1.exe}, @file{cc1plus.exe}, etc., in order to gain |
| 522 |
access to the symbols provided by GCC. This means that on Windows a |
| 523 |
plugin is language-specific, for example, for C, C++, etc. If you wish |
| 524 |
to use your plugin with multiple languages, then you will need to |
| 525 |
build multiple plugin libraries and either instruct your users on how |
| 526 |
to load the correct version or provide a compiler wrapper that does |
| 527 |
this automatically. |
| 528 |
|
| 529 |
Additionally, on Windows the plugin library has to export the |
| 530 |
@code{plugin_is_GPL_compatible} and @code{plugin_init} symbols. If you |
| 531 |
do not wish to modify the source code of your plugin, then you can use |
| 532 |
the @option{-Wl,--export-all-symbols} option or provide a suitable DEF |
| 533 |
file. Alternatively, you can export just these two symbols by decorating |
| 534 |
them with @code{__declspec(dllexport)}, for example: |
| 535 |
|
| 536 |
@smallexample |
| 537 |
#ifdef _WIN32 |
| 538 |
__declspec(dllexport) |
| 539 |
#endif |
| 540 |
int plugin_is_GPL_compatible; |
| 541 |
|
| 542 |
#ifdef _WIN32 |
| 543 |
__declspec(dllexport) |
| 544 |
#endif |
| 545 |
int plugin_init (plugin_name_args *, plugin_gcc_version *) |
| 546 |
@end smallexample |
| 547 |
|
| 548 |
The import libraries are installed into the @code{plugin} directory |
| 549 |
and their names are derived by appending the @code{.a} extension to |
| 550 |
the backend executable names, for example, @file{cc1.exe.a}, |
| 551 |
@file{cc1plus.exe.a}, etc. The following command line shows how to |
| 552 |
build the single source file plugin on Windows to be used with the C++ |
| 553 |
compiler: |
| 554 |
|
| 555 |
@smallexample |
| 556 |
g++ -I`gcc -print-file-name=plugin`/include -shared -Wl,--export-all-symbols \ |
| 557 |
-o plugin.dll plugin.cc `gcc -print-file-name=plugin`/cc1plus.exe.a |
| 558 |
@end smallexample |
| 559 |
|
| 560 |
When a plugin needs to use @command{gengtype}, be sure that both |
| 561 |
@file{gengtype} and @file{gtype.state} have the same version as the |
| 562 |
GCC for which the plugin is built. |