2011-03-11 Richard Guenther <rguenther@suse.de>

[pf3gnuchains/gcc-fork.git] / gcc / doc / plugins.texi

diff --git a/gcc/doc/plugins.texi b/gcc/doc/plugins.texi
index a1ca1de..767cee8 100644 (file)
--- a/gcc/doc/plugins.texi
+++ b/gcc/doc/plugins.texi
@@ -1,4 +1,4 @@
-@c Copyright (c) 2009 Free Software Foundation, Inc.
+@c Copyright (c) 2009, 2010 Free Software Foundation, Inc.
 @c Free Software Foundation, Inc.
 @c This is part of the GCC manual.
 @c For copying conditions, see the file gcc.texi.
@@ -16,12 +16,17 @@ process.
 
 Plugins are loaded with 
 
-@option{-fplugin=/path/to/NAME.so} @option{-fplugin-arg-NAME-<key1>[=<value1>]}
+@option{-fplugin=/path/to/@var{name}.so} @option{-fplugin-arg-@var{name}-@var{key1}[=@var{value1}]}
 
 The plugin arguments are parsed by GCC and passed to respective
 plugins as key-value pairs. Multiple plugins can be invoked by
 specifying multiple @option{-fplugin} arguments.
 
+A plugin can be simply given by its short name (no dots or
+slashes). When simply passing @option{-fplugin=@var{name}}, the plugin is
+loaded from the @file{plugin} directory, so @option{-fplugin=@var{name}} is
+the same as @option{-fplugin=`gcc -print-file-name=plugin`/@var{name}.so},
+using backquote shell syntax to query the @file{plugin} directory.
 
 @section Plugin API
 
@@ -40,13 +45,15 @@ If this symbol does not exist, the compiler will emit a fatal error
 and exit with the error message:
 
 @smallexample
-fatal error: plugin <name> is not licensed under a GPL-compatible license
-<name>: undefined symbol: plugin_is_GPL_compatible
+fatal error: plugin @var{name} is not licensed under a GPL-compatible license
+@var{name}: undefined symbol: plugin_is_GPL_compatible
 compilation terminated
 @end smallexample
 
-The type of the symbol is irrelevant.  The compiler merely asserts that
-it exists in the global scope.  Something like this is enough:
+The declared type of the symbol should be int, to match a forward declaration
+in @file{gcc-plugin.h} that suppresses C++ mangling.  It does not need to be in
+any allocated section, though.  The compiler merely asserts that
+the symbol exists in the global scope.  Something like this is enough:
 
 @smallexample
 int plugin_is_GPL_compatible;
@@ -407,6 +414,9 @@ On most systems, you can query this @code{plugin} directory by
 invoking @command{gcc -print-file-name=plugin} (replace if needed
 @command{gcc} with the appropriate program path).
 
+Inside plugins, this @code{plugin} directory name can be queried by
+calling @code{default_plugin_dir_name ()}.
+
 The following GNU Makefile excerpt shows how to build a simple plugin:
 
 @smallexample