← Back to branch summary

~ubuntu-branches/debian/sid/gnat-4.4/sid

« back to all changes in this revision

Viewing changes to debian/patches/gcc-plugins-branch-doc.diff

  • Committer: Bazaar Package Importer
  • Author(s): Ludovic Brenta
  • Date: 2010-05-09 23:28:13 UTC
  • mfrom: (1.1.4 upstream)
  • Revision ID: james.westby@ubuntu.com-20100509232813-bykj33gg0mc34opr
Tags: 4.4.4-2
* debian/control.m4, debian/control: make upgrades from Lenny work without
  broken packages or hard decisions.
  (gnat-4.4): replace all previous versions of gnat-X.Y.
  (libgnat{vsn,prj}4.4-dev):
  - Replace the corresponding 4.3 package in addition to Conflicting with it.
  - Suggest the -dbg package, too.
  (libgnat{vsn,prj}4.4-dbg):
  - Depend on the -dev package, too.
  - Do not recommend gnat-gdb, superseded by gdb.
  (libgnatprj4.4-dbg): do not recommend libgnatprj-dev, no longer in the archive.

Show diffs side-by-side

added added

removed removed

Lines of Context:
debian/patches/gcc-plugins-branch-doc.diff
 
1
# DP: Backport of plugins to the 4.4 branch
 
2
 
 
3
svn diff svn://gcc.gnu.org/svn/gcc/branches/gcc-4_4-branch@157307 svn://gcc.gnu.org/svn/gcc/branches/gcc-4_4-plugins \
 
4
        | sed -r 's,^--- (\S+)\t(\S+)(.*)$,--- a/src/\1\t\2,;s,^\+\+\+ (\S+)\t(\S+)(.*)$,+++ b/src/\1\t\2,'
 
5
 
 
6
Index: gcc/doc/sourcebuild.texi
 
7
===================================================================
 
8
--- a/src/gcc/doc/sourcebuild.texi      (.../gcc-4_4-branch)
 
9
+++ b/src/gcc/doc/sourcebuild.texi      (.../gcc-4_4-plugins)
 
10
@@ -612,6 +612,8 @@
 
11
 @item install-man
 
12
 Install man pages for the front end.  This target should ignore
 
13
 errors.
 
14
+@item install-plugin
 
15
+Install headers needed for plugins.
 
16
 @item srcextra
 
17
 Copies its dependencies into the source directory.  This generally should
 
18
 be used for generated files such as Bison output files which are not
 
19
Index: gcc/doc/plugins.texi
 
20
===================================================================
 
21
--- a/src/gcc/doc/plugins.texi  (.../gcc-4_4-branch)
 
22
+++ b/src/gcc/doc/plugins.texi  (.../gcc-4_4-plugins)
 
23
@@ -0,0 +1,299 @@
 
24
+@c Copyright (c) 2009 Free Software Foundation, Inc.
 
25
+@c Free Software Foundation, Inc.
 
26
+@c This is part of the GCC manual.
 
27
+@c For copying conditions, see the file gcc.texi.
 
28
+
 
29
+@node Plugins
 
30
+@chapter Plugins
 
31
+@cindex Plugins
 
32
+
 
33
+@section Loading Plugins
 
34
+
 
35
+Plugins are supported on platforms that support @option{-ldl
 
36
+-rdynamic}.  They are loaded by the compiler using @code{dlopen}
 
37
+and invoked at pre-determined locations in the compilation
 
38
+process.
 
39
+
 
40
+Plugins are loaded with 
 
41
+
 
42
+@option{-fplugin=/path/to/NAME.so} @option{-fplugin-arg-NAME-<key1>[=<value1>]}
 
43
+
 
44
+The plugin arguments are parsed by GCC and passed to respective
 
45
+plugins as key-value pairs. Multiple plugins can be invoked by
 
46
+specifying multiple @option{-fplugin} arguments.
 
47
+
 
48
+
 
49
+@section Plugin API
 
50
+
 
51
+Plugins are activated by the compiler at specific events as defined in
 
52
+@file{gcc-plugin.h}.  For each event of interest, the plugin should
 
53
+call @code{register_callback} specifying the name of the event and
 
54
+address of the callback function that will handle that event.
 
55
+
 
56
+The header @file{gcc-plugin.h} must be the first gcc header to be included.
 
57
+
 
58
+@subsection Plugin initialization
 
59
+
 
60
+Every plugin should export a function called @code{plugin_init} that
 
61
+is called right after the plugin is loaded. This function is
 
62
+responsible for registering all the callbacks required by the plugin
 
63
+and do any other required initialization.
 
64
+
 
65
+This function is called from @code{compile_file} right before invoking
 
66
+the parser.  The arguments to @code{plugin_init} are:
 
67
+
 
68
+@itemize @bullet
 
69
+@item @code{plugin_info}: Plugin invocation information.
 
70
+@item @code{version}: GCC version.
 
71
+@end itemize
 
72
+
 
73
+The @code{plugin_info} struct is defined as follows:
 
74
+
 
75
+@smallexample
 
76
+struct plugin_name_args
 
77
+@{
 
78
+  char *base_name;              /* Short name of the plugin
 
79
+                                   (filename without .so suffix). */
 
80
+  const char *full_name;        /* Path to the plugin as specified with
 
81
+                                   -fplugin=. */
 
82
+  int argc;                     /* Number of arguments specified with
 
83
+                                   -fplugin-arg-.... */
 
84
+  struct plugin_argument *argv; /* Array of ARGC key-value pairs. */
 
85
+  const char *version;          /* Version string provided by plugin. */
 
86
+  const char *help;             /* Help string provided by plugin. */
 
87
+@}
 
88
+@end smallexample
 
89
+
 
90
+If initialization fails, @code{plugin_init} must return a non-zero
 
91
+value.  Otherwise, it should return 0.
 
92
+
 
93
+The version of the GCC compiler loading the plugin is described by the
 
94
+following structure:
 
95
+
 
96
+@smallexample
 
97
+struct plugin_gcc_version
 
98
+@{
 
99
+  const char *basever;
 
100
+  const char *datestamp;
 
101
+  const char *devphase;
 
102
+  const char *revision;
 
103
+  const char *configuration_arguments;
 
104
+@};
 
105
+@end smallexample
 
106
+
 
107
+The function @code{plugin_default_version_check} takes two pointers to
 
108
+such structure and compare them field by field. It can be used by the
 
109
+plugin's @code{plugin_init} function.
 
110
+
 
111
+
 
112
+@subsection Plugin callbacks
 
113
+
 
114
+Callback functions have the following prototype:
 
115
+
 
116
+@smallexample
 
117
+/* The prototype for a plugin callback function.
 
118
+     gcc_data  - event-specific data provided by GCC
 
119
+     user_data - plugin-specific data provided by the plug-in.  */
 
120
+typedef void (*plugin_callback_func)(void *gcc_data, void *user_data);
 
121
+@end smallexample
 
122
+
 
123
+Callbacks can be invoked at the following pre-determined events:
 
124
+
 
125
+
 
126
+@smallexample
 
127
+enum plugin_event
 
128
+@{
 
129
+  PLUGIN_PASS_MANAGER_SETUP,    /* To hook into pass manager.  */
 
130
+  PLUGIN_FINISH_TYPE,           /* After finishing parsing a type.  */
 
131
+  PLUGIN_FINISH_UNIT,           /* Useful for summary processing.  */
 
132
+  PLUGIN_CXX_CP_PRE_GENERICIZE, /* Allows to see low level AST in C++ FE.  */
 
133
+  PLUGIN_FINISH,                /* Called before GCC exits.  */
 
134
+  PLUGIN_INFO,                  /* Information about the plugin. */
 
135
+  PLUGIN_GGC_START,            /* Called at start of GCC Garbage Collection. */
 
136
+  PLUGIN_GGC_MARKING,          /* Extend the GGC marking. */
 
137
+  PLUGIN_GGC_END,              /* Called at end of GGC. */
 
138
+  PLUGIN_REGISTER_GGC_ROOTS,   /* Register an extra GGC root table. */
 
139
+  PLUGIN_ATTRIBUTES,            /* Called during attribute registration */
 
140
+  PLUGIN_START_UNIT,            /* Called before processing a translation unit.  */
 
141
+  PLUGIN_EVENT_LAST             /* Dummy event used for indexing callback
 
142
+                                   array.  */
 
143
+@};
 
144
+@end smallexample
 
145
+
 
146
+
 
147
+To register a callback, the plugin calls @code{register_callback} with
 
148
+the arguments:
 
149
+
 
150
+@itemize
 
151
+@item @code{char *name}: Plugin name.
 
152
+@item @code{enum plugin_event event}: The event code.
 
153
+@item @code{plugin_callback_func callback}: The function that handles @code{event}.
 
154
+@item @code{void *user_data}: Pointer to plugin-specific data.
 
155
+@end itemize
 
156
+
 
157
+For the PLUGIN_PASS_MANAGER_SETUP, PLUGIN_INFO, and
 
158
+PLUGIN_REGISTER_GGC_ROOTS pseudo-events the @code{callback} should be
 
159
+null, and the @code{user_data} is specific.
 
160
+
 
161
+@section Interacting with the pass manager
 
162
+
 
163
+There needs to be a way to add/reorder/remove passes dynamically. This
 
164
+is useful for both analysis plugins (plugging in after a certain pass
 
165
+such as CFG or an IPA pass) and optimization plugins.
 
166
+
 
167
+Basic support for inserting new passes or replacing existing passes is
 
168
+provided. A plugin registers a new pass with GCC by calling
 
169
+@code{register_callback} with the @code{PLUGIN_PASS_MANAGER_SETUP}
 
170
+event and a pointer to a @code{struct plugin_pass} object defined as follows
 
171
+
 
172
+@smallexample
 
173
+enum pass_positioning_ops
 
174
+@{
 
175
+  PASS_POS_INSERT_AFTER,  // Insert after the reference pass.
 
176
+  PASS_POS_INSERT_BEFORE, // Insert before the reference pass.
 
177
+  PASS_POS_REPLACE        // Replace the reference pass.
 
178
+@};
 
179
+
 
180
+struct plugin_pass
 
181
+@{
 
182
+  struct opt_pass *pass;            /* New pass provided by the plugin.  */
 
183
+  const char *reference_pass_name;  /* Name of the reference pass for hooking
 
184
+                                       up the new pass.  */
 
185
+  int ref_pass_instance_number;     /* Insert the pass at the specified
 
186
+                                       instance number of the reference pass.  */
 
187
+                                    /* Do it for every instance if it is 0.  */
 
188
+  enum pass_positioning_ops pos_op; /* how to insert the new pass.  */
 
189
+@};
 
190
+
 
191
+
 
192
+/* Sample plugin code that registers a new pass.  */
 
193
+int
 
194
+plugin_init (struct plugin_name_args *plugin_info,
 
195
+             struct plugin_gcc_version *version)
 
196
+@{
 
197
+  struct plugin_pass pass_info;
 
198
+
 
199
+  ...
 
200
+
 
201
+  /* Code to fill in the pass_info object with new pass information.  */
 
202
+
 
203
+  ...
 
204
+
 
205
+  /* Register the new pass.  */
 
206
+  register_callback (plugin_info->base_name, PLUGIN_PASS_MANAGER_SETUP, NULL, &pass_info);
 
207
+
 
208
+  ...
 
209
+@}
 
210
+@end smallexample
 
211
+
 
212
+
 
213
+@section Interacting with the GCC Garbage Collector 
 
214
+
 
215
+Some plugins may want to be informed when GGC (the GCC Garbage
 
216
+Collector) is running. They can register callbacks for the
 
217
+@code{PLUGIN_GGC_START} and @code{PLUGIN_GGC_END} events (for which
 
218
+the callback is called with a null @code{gcc_data}) to be notified of
 
219
+the start or end of the GCC garbage collection.
 
220
+
 
221
+Some plugins may need to have GGC mark additional data. This can be
 
222
+done by registering a callback (called with a null @code{gcc_data})
 
223
+for the @code{PLUGIN_GGC_MARKING} event. Such callbacks can call the
 
224
+@code{ggc_set_mark} routine, preferably thru the @code{ggc_mark} macro
 
225
+(and conversely, these routines should usually not be used in plugins
 
226
+outside of the @code{PLUGIN_GGC_MARKING} event).  
 
227
+
 
228
+Some plugins may need to add extra GGC root tables, e.g. to handle
 
229
+their own @code{GTY}-ed data. This can be done with the
 
230
+@code{PLUGIN_REGISTER_GGC_ROOTS} pseudo-event with a null callback and
 
231
+the extra root table as @code{user_data}.  Running the @code{gengtype
 
232
+-p @var{source-dir} @var{file-list} @var{plugin*.c} ...} utility
 
233
+generates this extra root table.
 
234
+
 
235
+You should understand the details of memory management inside GCC
 
236
+before using @code{PLUGIN_GGC_MARKING} or
 
237
+@code{PLUGIN_REGISTER_GGC_ROOTS}.
 
238
+
 
239
+
 
240
+@section Giving information about a plugin
 
241
+
 
242
+A plugin should give some information to the user about itself. This
 
243
+uses the following structure:
 
244
+
 
245
+@smallexample
 
246
+struct plugin_info
 
247
+@{
 
248
+  const char *version;
 
249
+  const char *help;
 
250
+@};
 
251
+@end smallexample
 
252
+
 
253
+Such a structure is passed as the @code{user_data} by the plugin's
 
254
+init routine using @code{register_callback} with the
 
255
+@code{PLUGIN_INFO} pseudo-event and a null callback.
 
256
+
 
257
+@section Registering custom attributes
 
258
+
 
259
+For analysis purposes it is useful to be able to add custom attributes.
 
260
+
 
261
+The @code{PLUGIN_ATTRIBUTES} callback is called during attribute
 
262
+registration. Use the @code{register_attribute} function to register
 
263
+custom attributes.
 
264
+
 
265
+@smallexample
 
266
+/* Attribute handler callback */
 
267
+static tree
 
268
+handle_user_attribute (tree *node, tree name, tree args,
 
269
+                       int flags, bool *no_add_attrs)
 
270
+@{
 
271
+  return NULL_TREE;
 
272
+@}
 
273
+
 
274
+/* Attribute definition */
 
275
+static struct attribute_spec user_attr =
 
276
+  @{ "user", 1, 1, false,  false, false, handle_user_attribute @};
 
277
+
 
278
+/* Plugin callback called during attribute registration.
 
279
+Registered with register_callback (plugin_name, PLUGIN_ATTRIBUTES, register_attributes, NULL)
 
280
+*/
 
281
+static void 
 
282
+register_attributes (void *event_data, void *data)
 
283
+@{
 
284
+  warning (0, G_("Callback to register attributes"));
 
285
+  register_attribute (&user_attr);
 
286
+@}
 
287
+
 
288
+@end smallexample
 
289
+
 
290
+
 
291
+@section Building GCC plugins
 
292
+
 
293
+If plugins are enabled, GCC installs the headers needed to build a
 
294
+plugin (somehwere in the installation tree, e.g. under
 
295
+@file{/usr/local}).  In particular a @file{plugin/include} directory
 
296
+is installed, containing all the header files needed to build plugins.
 
297
+
 
298
+On most systems, you can query this @code{plugin} directory by
 
299
+invoking @command{gcc -print-file-name=plugin} (replace if needed
 
300
+@command{gcc} with the appropriate program path).
 
301
+
 
302
+The following GNU Makefile excerpt shows how to build a simple plugin:
 
303
+
 
304
+@smallexample
 
305
+GCC=gcc
 
306
+PLUGIN_SOURCE_FILES= plugin1.c plugin2.c
 
307
+PLUGIN_OBJECT_FILES= $(patsubst %.c,%.o,$(PLUGIN_SOURCE_FILES))
 
308
+GCCPLUGINS_DIR:= $(shell $(GCC) -print-file-name=plugin)
 
309
+CFLAGS+= -I$(GCCPLUGINS_DIR)/include -fPIC -O2
 
310
+
 
311
+plugin.so: $(PLUGIN_OBJECT_FILES)
 
312
+   $(GCC) -shared $^ -o $@
 
313
+@end smallexample
 
314
+
 
315
+A single source file plugin may be built with @code{gcc -I`gcc
 
316
+-print-file-name=plugin`/include -fPIC -shared -O2 plugin.c -o
 
317
+plugin.so}, using backquote shell syntax to query the @file{plugin}
 
318
+directory.
 
319
+
 
320
+Plugins needing to use @command{gengtype} require a GCC build
 
321
+directory for the same version of GCC that they will be linked
 
322
+against.
 
323
Index: gcc/doc/gccint.texi
 
324
===================================================================
 
325
--- a/src/gcc/doc/gccint.texi   (.../gcc-4_4-branch)
 
326
+++ b/src/gcc/doc/gccint.texi   (.../gcc-4_4-plugins)
 
327
@@ -122,6 +122,7 @@
 
328
 * Collect2::        How @code{collect2} works; how it finds @code{ld}.
 
329
 * Header Dirs::     Understanding the standard header file directories.
 
330
 * Type Information:: GCC's memory management; generating type information.
 
331
+* Plugins::         Extending the compiler with plugins.
 
332
 
 
333
 * Funding::         How to help assure funding for free software.
 
334
 * GNU Project::     The GNU Project and GNU/Linux.
 
335
@@ -157,6 +158,7 @@
 
336
 @include collect2.texi
 
337
 @include headerdirs.texi
 
338
 @include gty.texi
 
339
+@include plugins.texi
 
340
 
 
341
 @include funding.texi
 
342
 @include gnu.texi
 
343
Index: gcc/doc/invoke.texi
 
344
===================================================================
 
345
--- a/src/gcc/doc/invoke.texi   (.../gcc-4_4-branch)
 
346
+++ b/src/gcc/doc/invoke.texi   (.../gcc-4_4-plugins)
 
347
@@ -164,7 +164,7 @@
 
348
 @xref{Overall Options,,Options Controlling the Kind of Output}.
 
349
 @gccoptlist{-c  -S  -E  -o @var{file}  -combine  -pipe  -pass-exit-codes  @gol
 
350
 -x @var{language}  -v  -###  --help@r{[}=@var{class}@r{[},@dots{}@r{]]}  --target-help  @gol
 
351
---version -wrapper@@@var{file}}
 
352
+--version -wrapper@@@var{file} -fplugin=@var{file} -fplugin-arg-@var{name}=@var{arg}}
 
353
 
 
354
 @item C Language Options
 
355
 @xref{C Dialect Options,,Options Controlling C Dialect}.
 
356
@@ -1297,6 +1297,19 @@
 
357
 This will invoke all subprograms of gcc under "gdb --args",
 
358
 thus cc1 invocation will be "gdb --args cc1 ...".
 
359
 
 
360
+@item -fplugin=@var{name}.so
 
361
+Load the plugin code in file @var{name}.so, assumed to be a
 
362
+shared object to be dlopen'd by the compiler.  The base name of
 
363
+the shared object file is used to identify the plugin for the
 
364
+purposes of argument parsing (See
 
365
+@option{-fplugin-arg-@var{name}-@var{key}=@var{value}} below).
 
366
+Each plugin should define the callback functions specified in the
 
367
+Plugins API.
 
368
+
 
369
+@item -fplugin-arg-@var{name}-@var{key}=@var{value}
 
370
+Define an argument called @var{key} with a value of @var{value}
 
371
+for the plugin called @var{name}.
 
372
+
 
373
 @include @value{srcdir}/../libiberty/at-file.texi
 
374
 @end table
 
375
 
 
376
Index: gcc/doc/gty.texi
 
377
===================================================================
 
378
--- a/src/gcc/doc/gty.texi      (.../gcc-4_4-branch)
 
379
+++ b/src/gcc/doc/gty.texi      (.../gcc-4_4-plugins)
 
380
@@ -450,6 +450,14 @@
 
381
 somewhere.  It will be called @file{gtype-@var{lang}.h}, where
 
382
 @var{lang} is the name of the subdirectory the language is contained in.
 
383
 
 
384
+Plugins can add additional root tables.  Run the @code{gengtype}
 
385
+utility in plugin mode as @code{gengtype -p @var{source-dir}
 
386
+@var{file-list} @var{plugin*.c}} with your plugin files
 
387
+@var{plugin*.c} using @code{GTY} to generate the corresponding
 
388
+@var{gt-plugin*.h} files.  The GCC build tree is needed to be present in
 
389
+that mode.
 
390
+
 
391
+
 
392
 @node Invoking the garbage collector
 
393
 @section How to invoke the garbage collector
 
394
 @cindex garbage collector, invocation
 
395
Index: gcc/doc/install.texi
 
396
===================================================================
 
397
--- a/src/gcc/doc/install.texi  (.../gcc-4_4-branch)
 
398
+++ b/src/gcc/doc/install.texi  (.../gcc-4_4-plugins)
 
399
@@ -1740,6 +1740,9 @@
 
400
 @item --enable-aot-compile-rpm
 
401
 Adds aot-compile-rpm to the list of installed scripts.
 
402
 
 
403
+@item --enable-browser-plugin
 
404
+Build the gcjwebplugin web browser plugin.
 
405
+
 
406
 @table @code
 
407
 @item ansi
 
408
 Use the single-byte @code{char} and the Win32 A functions natively,