Re: trunk patch: documenting how to build plugins.

[Basile STARYNKEVITCH <basile at starynkevitch dot net>]

Rafael Espindola wrote:
> > gcc/Changelog:
> > 2009-06-16  Basile Starynkevitch  <basile@starynkevitch.net>
> >   * doc/plugins.texi (Building GCC plugins): Added new section.
> >     
>
>   

Thanks Rafael for your comments!

> Some comments: 
>   
[skipped but followed in this improved patch]. The gcc/Changelog would 
be the same as above, except for the date.

The last sentence explains that some plugin could indeed need the source 
or build tree. This could happen because of gengtype, or because the 
plugin might want to use some feature or function of GCC which is not 
declared inside the plugin/include directory. IIRC the plugin dogma 
(which I agree with) is : there is no stable GCC internal API!

I am attaching a patch to trunk rev. 148609.

Regards.

--
Basile STARYNKEVITCH         http://starynkevitch.net/Basile/
email: basile<at>starynkevitch<dot>net mobile: +33 6 8501 2359
8, rue de la Faiencerie, 92340 Bourg La Reine, France
*** opinions {are only mines, sont seulement les miennes} ***

Index: gcc/doc/plugins.texi
===================================================================
--- gcc/doc/plugins.texi	(revision 148609)
+++ gcc/doc/plugins.texi	(working copy)
@@ -262,3 +262,38 @@ register_attributes (void *event_data, void *data)
 @}
 
 @end smallexample
+
+
+@section Building GCC plugins
+
+If plugins are enabled, GCC installs the headers needed to build a
+plugin (somehwere in the installation tree, e.g. under
+@code{/usr/local}).  In particular a @code{plugin} directory has been
+installed, and it contains a @code{plugin/include} sub-directory with
+all the header files useful for building plugins.
+
+On most systems, you can query this @code{plugin} directory by
+invoking @code{@var{gcc} -print-file-name=plugin} (replace if needed
+@var{gcc} with the appropriate program path).
+
+The following GNU Makefile except shows how to build a simple plugin:
+
+@smallexample
+GCC=gcc
+PLUGIN_SOURCE_FILES= plugin1.c plugin2.c
+PLUGIN_OBJECT_FILES= $(patsubst %.c,%.o,$(PLUGIN_SOURCE_FILES))
+GCCPLUGINS_DIR:= $(shell $(GCC) -print-file-name=plugin)
+CFLAGS+= -I$(GCCPLUGINS_DIR)/include -fPIC -O2
+
+plugin.so: $(PLUGIN_OBJECT_FILES)
+   $(GCC) -shared $^ -o $@
+@end smallexample
+
+A single source file plugin could even be built with @code{gcc -I`gcc
+-print-file-name=plugin`/include -fPIC -shared -O2 plugin.c -o
+plugin.so}, using backquote shell syntax to query the @code{plugin}
+directory.
+
+Some complex plugins (e.g. those needing @code{gengtype} or using GCC
+stuff outside of @code{plugin/ionclude}) could require both source and
+build directories of GCC.