This is the mail archive of the
gcc-patches@gcc.gnu.org
mailing list for the GCC project.
slightly improved documention for plugin pragmas
- From: Basile STARYNKEVITCH <basile at starynkevitch dot net>
- To: gcc-patches <gcc-patches at gcc dot gnu dot org>
- Date: Tue, 10 Nov 2009 20:56:34 +0100
- Subject: slightly improved documention for plugin pragmas
Hello All,
The attached patch to trunk rev 154075 did bootstap, and added more documentation about pragmas provided by plugins.
http://gcc.gnu.org/ml/gcc-patches/2009-11/msg00197.html
http://gcc.gnu.org/ml/gcc-patches/2009-11/msg00371.html
Also, I added in the user documentation that attributes & pragmas can be provided by plugins.
############
gcc/ChangeLog:
2009-11-10 Basile Starynkevitch <basile@starynkevitch.net>
* doc/plugins.texi (Registering custom attributes): section
renamed as (Registering custom attributes or pragmas).
Mentions custom attributes & pragmas, and c_register_pragma, with
a small example.
* doc/cpp.texi (Pragmas): Mentions that plugins can provide their
pragmas.
* doc/extend.texi (Function Attributes): Mentions that plugin can
provide their attributes.
############
Feel free to improve the English language. I can apply this documentation patch if someone gives me an OK.
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 154075)
+++ gcc/doc/plugins.texi (working copy)
@@ -261,9 +261,10 @@ Such a structure is passed as the @code{user_data}
init routine using @code{register_callback} with the
@code{PLUGIN_INFO} pseudo-event and a null callback.
-@section Registering custom attributes
+@section Registering custom attributes or pragmas
-For analysis purposes it is useful to be able to add custom attributes.
+For analysis (or other) purposes it is useful to be able to add custom
+attributes or pragmas.
The @code{PLUGIN_ATTRIBUTES} callback is called during attribute
registration. Use the @code{register_attribute} function to register
@@ -295,6 +296,28 @@ register_attributes (void *event_data, void *data)
@end smallexample
+The @code{PLUGIN_PRAGMAS} callback is called during pragmas
+registration. Use the @code{c_register_pragma} or
+@code{c_register_pragma_with_expansion} functions to register custom
+pragmas.
+
+@smallexample
+/* Plugin callback called during pragmas registration. Registered with
+ register_callback (plugin_name, PLUGIN_PRAGMAS,
+ register_my_pragma, NULL);
+*/
+static void
+register_my_pragma (void *event_data, void *data)
+@{
+ warning (0, G_("Callback to register pragmas"));
+ c_register_pragma ("GCCPLUGIN", "sayhello", handle_pragma_sayhello);
+@}
+@end smallexample
+
+It is suggested to pass @code{"GCCPLUGIN"} (or a short name identifying
+your plugin) as the ``space'' argument of your pragma.
+
+
@section Building GCC plugins
If plugins are enabled, GCC installs the headers needed to build a
Index: gcc/doc/cpp.texi
===================================================================
--- gcc/doc/cpp.texi (revision 154075)
+++ gcc/doc/cpp.texi (working copy)
@@ -3541,6 +3541,8 @@ This manual documents the pragmas which are meanin
preprocessor itself. Other pragmas are meaningful to the C or C++
compilers. They are documented in the GCC manual.
+GCC plugins may provide their own pragmas.
+
@ftable @code
@item #pragma GCC dependency
@code{#pragma GCC dependency} allows you to check the relative dates of
Index: gcc/doc/extend.texi
===================================================================
--- gcc/doc/extend.texi (revision 154075)
+++ gcc/doc/extend.texi (working copy)
@@ -1922,6 +1922,8 @@ particular target systems. Other attributes, incl
are supported for variables declarations (@pxref{Variable Attributes})
and for types (@pxref{Type Attributes}).
+GCC plugins may provide their own attributes.
+
You may also specify attributes with @samp{__} preceding and following
each keyword. This allows you to use them in header files without
being concerned about a possible macro of the same name. For example,