trunk patch: documenting how to build plugins.

[Basile STARYNKEVITCH <basile at starynkevitch dot net>]

Hello All

I believe we should document how to build plugins.
See http://gcc.gnu.org/ml/gcc/2009-06/msg00334.html for detailed 
motivations.

I wrote a small section to the Plugins chapter of the internal 
documentation to explain how to build plugins. Patch to trunk rev148518 
is attached.

Comments (and spelling corrections) are welcome (I am not a native 
English speaker).


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


By the way, perhaps some utilities (like gengtype and other generators) 
might be installed for plugin use. What do people think?
[otherwise, some plugins still need the entire GCC build & source trees 
to be compiled, as I wrote in the last sentence of the patch]

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 148518)
+++ gcc/doc/plugins.texi	(working copy)
@@ -262,3 +262,36 @@
 @}
 
 @end smallexample
+
+
+@section Building GCC plugins
+
+Once a GCC with plugins has been installed, a set of files useful for
+compiling plugins is available (in the installed prefix file tree).
+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).
+
+Therefore, most simple plugins could be built, using GNU make, with
+the following lines in their Makefile:
+
+@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 could require both source and build directories of GCC.