GCC trunk 4.9: documentation patch on plugins

GCC trunk 4.9: documentation patch on plugins

[Basile Starynkevitch]

[-- Attachment #1: Type: text/plain, Size: 952 bytes --]

Dear all,

The attached patch to trunk svn.rev 207422 is slightly improving the documentation 
of plugins  (notably the few features & bugfixes I have introduced in 4.9)


#### gcc/ChangeLog entry

2014-02-03  Basile Starynkevitch  <basile@starynkevitch.net>

	* doc/plugins.texi (Plugin callbacks): Mention PLUGIN_INCLUDE_FILE.
	Italicize plugin event names in description.  Explain that 
	PLUGIN_PRAGMAS has no sense for lto1. Explain PLUGIN_INCLUDE_FILE. 
	Remind that no GCC functions should be called after PLUGIN_FINISH.
	Explain what pragmas with expansion are.

####

Comments are welcome. Recall that I am not a native English speaker, 
so please improve my wordings in the documentation.

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} ***

[-- Attachment #2: gcctrunk-plugindoc-r207422.diff --]
[-- Type: text/x-diff, Size: 3312 bytes --]

Index: gcc/doc/plugins.texi
===================================================================
--- gcc/doc/plugins.texi	(revision 207422)
+++ gcc/doc/plugins.texi	(working copy)
@@ -209,6 +209,10 @@
   PLUGIN_EARLY_GIMPLE_PASSES_END,
   /* Called when a pass is first instantiated.  */
   PLUGIN_NEW_PASS,
+/* Called when a file is #include-d or given thru #line directive.
+   Could happen many times.  The event data is the included file path,
+   as a const char* pointer.  */
+  PLUGIN_INCLUDE_FILE,
 
   PLUGIN_EVENT_FIRST_DYNAMIC    /* Dummy event used for indexing callback
                                    array.  */
@@ -229,15 +233,27 @@
 @item @code{void *user_data}: Pointer to plugin-specific data.
 @end itemize
 
-For the PLUGIN_PASS_MANAGER_SETUP, PLUGIN_INFO, PLUGIN_REGISTER_GGC_ROOTS
-and PLUGIN_REGISTER_GGC_CACHES pseudo-events the @code{callback} should be
-null, and the @code{user_data} is specific.
+For the @i{PLUGIN_PASS_MANAGER_SETUP}, @i{PLUGIN_INFO},
+@i{PLUGIN_REGISTER_GGC_ROOTS} and @i{PLUGIN_REGISTER_GGC_CACHES}
+pseudo-events the @code{callback} should be null, and the
+@code{user_data} is specific.
 
-When the PLUGIN_PRAGMAS event is triggered (with a null
-pointer as data from GCC), plugins may register their own pragmas
-using functions like @code{c_register_pragma} or
-@code{c_register_pragma_with_expansion}.
+When the @i{PLUGIN_PRAGMAS} event is triggered (with a null pointer as
+data from GCC), plugins may register their own pragmas.  Notice that
+pragmas are not available from @file{lto1}, so plugins used with
+@code{-flto} option to GCC during link-time optimization cannot use
+pragmas and do not even see functions like @code{c_register_pragma} or
+@code{pragma_lex}.
 
+The @i{PLUGIN_INCLUDE_FILE} event, with a @code{const char*} file path as
+GCC data, is triggered for processing of @code{#include} or
+@code{#line} directives.
+
+The @i{PLUGIN_FINISH} event is the last time that plugins can call GCC
+functions, notably emit diagnostics with @code{warning}, @code{error}
+etc.
+
+
 @node Plugins pass
 @section Interacting with the pass manager
 
@@ -376,10 +392,13 @@
 @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.
+The @i{PLUGIN_PRAGMAS} callback is called once during pragmas
+registration. Use the @code{c_register_pragma},
+@code{c_register_pragma_with_data},
+@code{c_register_pragma_with_expansion},
+@code{c_register_pragma_with_expansion_and_data} functions to register
+custom pragmas and their handlers (which often want to call
+@code{pragma_lex}) from @file{c-family/c-pragma.h}.
 
 @smallexample
 /* Plugin callback called during pragmas registration. Registered with
@@ -397,7 +416,15 @@
 It is suggested to pass @code{"GCCPLUGIN"} (or a short name identifying
 your plugin) as the ``space'' argument of your pragma.
 
+Pragmas registered with @code{c_register_pragma_with_expansion} or
+@code{c_register_pragma_with_expansion_and_data} are allowing
+preprocessor expansions, like e.g.
 
+@smallexample
+#define NUMBER 10
+#pragma GCCPLUGIN foothreshold (NUMBER)
+@end smallexample
+
 @node Plugins recording
 @section Recording information about pass execution
 

Ping GCC trunk 4.9: documentation patch on plugins

[Basile Starynkevitch]

Hello All,

I am pinging this documentation patch
http://gcc.gnu.org/ml/gcc-patches/2014-02/msg00074.html

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} ***

Ping^2 GCC trunk 4.9: documentation patch on plugins

[Basile Starynkevitch]

Hello All,

I am pinging again this documentation patch
http://gcc.gnu.org/ml/gcc-patches/2014-02/msg00074.html
(pinged at http://gcc.gnu.org/ml/gcc-patches/2014-02/msg01002.html on febµ.17th 2014)

#### gcc/ChangeLog entry

2014-03-08  Basile Starynkevitch  <basile@starynkevitch.net>

	* doc/plugins.texi (Plugin callbacks): Mention PLUGIN_INCLUDE_FILE.
	Italicize plugin event names in description.  Explain that 
	PLUGIN_PRAGMAS has no sense for lto1. Explain PLUGIN_INCLUDE_FILE. 
	Remind that no GCC functions should be called after PLUGIN_FINISH.
	Explain what pragmas with expansion are.

#### the patch:
Index: gcc/doc/plugins.texi
===================================================================
--- gcc/doc/plugins.texi	(revision 207422)
+++ gcc/doc/plugins.texi	(working copy)
@@ -209,6 +209,10 @@
   PLUGIN_EARLY_GIMPLE_PASSES_END,
   /* Called when a pass is first instantiated.  */
   PLUGIN_NEW_PASS,
+/* Called when a file is #include-d or given thru #line directive.
+   Could happen many times.  The event data is the included file path,
+   as a const char* pointer.  */
+  PLUGIN_INCLUDE_FILE,
 
   PLUGIN_EVENT_FIRST_DYNAMIC    /* Dummy event used for indexing callback
                                    array.  */
@@ -229,15 +233,27 @@
 @item @code{void *user_data}: Pointer to plugin-specific data.
 @end itemize
 
-For the PLUGIN_PASS_MANAGER_SETUP, PLUGIN_INFO, PLUGIN_REGISTER_GGC_ROOTS
-and PLUGIN_REGISTER_GGC_CACHES pseudo-events the @code{callback} should be
-null, and the @code{user_data} is specific.
+For the @i{PLUGIN_PASS_MANAGER_SETUP}, @i{PLUGIN_INFO},
+@i{PLUGIN_REGISTER_GGC_ROOTS} and @i{PLUGIN_REGISTER_GGC_CACHES}
+pseudo-events the @code{callback} should be null, and the
+@code{user_data} is specific.
 
-When the PLUGIN_PRAGMAS event is triggered (with a null
-pointer as data from GCC), plugins may register their own pragmas
-using functions like @code{c_register_pragma} or
-@code{c_register_pragma_with_expansion}.
+When the @i{PLUGIN_PRAGMAS} event is triggered (with a null pointer as
+data from GCC), plugins may register their own pragmas.  Notice that
+pragmas are not available from @file{lto1}, so plugins used with
+@code{-flto} option to GCC during link-time optimization cannot use
+pragmas and do not even see functions like @code{c_register_pragma} or
+@code{pragma_lex}.
 
+The @i{PLUGIN_INCLUDE_FILE} event, with a @code{const char*} file path as
+GCC data, is triggered for processing of @code{#include} or
+@code{#line} directives.
+
+The @i{PLUGIN_FINISH} event is the last time that plugins can call GCC
+functions, notably emit diagnostics with @code{warning}, @code{error}
+etc.
+
+
 @node Plugins pass
 @section Interacting with the pass manager
 
@@ -376,10 +392,13 @@
 @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.
+The @i{PLUGIN_PRAGMAS} callback is called once during pragmas
+registration. Use the @code{c_register_pragma},
+@code{c_register_pragma_with_data},
+@code{c_register_pragma_with_expansion},
+@code{c_register_pragma_with_expansion_and_data} functions to register
+custom pragmas and their handlers (which often want to call
+@code{pragma_lex}) from @file{c-family/c-pragma.h}.
 
 @smallexample
 /* Plugin callback called during pragmas registration. Registered with
@@ -397,7 +416,15 @@
 It is suggested to pass @code{"GCCPLUGIN"} (or a short name identifying
 your plugin) as the ``space'' argument of your pragma.
 
+Pragmas registered with @code{c_register_pragma_with_expansion} or
+@code{c_register_pragma_with_expansion_and_data} are allowing
+preprocessor expansions, like e.g.
 
+@smallexample
+#define NUMBER 10
+#pragma GCCPLUGIN foothreshold (NUMBER)
+@end smallexample
+
 @node Plugins recording
 @section Recording information about pass execution
 
#####

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} ***

Ping^3 GCC trunk 4.9: documentation patch on plugins

[Basile Starynkevitch]

On Sat, 2014-03-08 at 11:15 +0100, Basile Starynkevitch wrote:
> I am pinging again this documentation patch
> http://gcc.gnu.org/ml/gcc-patches/2014-02/msg00074.html
> (pinged at http://gcc.gnu.org/ml/gcc-patches/2014-02/msg01002.html on febµ.17th 2014)
and also pinged at
http://gcc.gnu.org/ml/gcc-patches/2014-03/msg00387.html on march 8th
2014
#### gcc/ChangeLog entry

2014-03-18  Basile Starynkevitch  <basile@starynkevitch.net>

        * doc/plugins.texi (Plugin callbacks): Mention
        PLUGIN_INCLUDE_FILE.
        Italicize plugin event names in description.  Explain that 
        PLUGIN_PRAGMAS has no sense for lto1. Explain
        PLUGIN_INCLUDE_FILE. 
        Remind that no GCC functions should be called after
        PLUGIN_FINISH.
        Explain what pragmas with expansion are.

#### the patch:
Index: gcc/doc/plugins.texi
===================================================================
--- gcc/doc/plugins.texi        (revision 207422)
+++ gcc/doc/plugins.texi        (working copy)
@@ -209,6 +209,10 @@
   PLUGIN_EARLY_GIMPLE_PASSES_END,
   /* Called when a pass is first instantiated.  */
   PLUGIN_NEW_PASS,
+/* Called when a file is #include-d or given thru #line directive.
+   Could happen many times.  The event data is the included file path,
+   as a const char* pointer.  */
+  PLUGIN_INCLUDE_FILE,
 
   PLUGIN_EVENT_FIRST_DYNAMIC    /* Dummy event used for indexing
callback
                                    array.  */
@@ -229,15 +233,27 @@
 @item @code{void *user_data}: Pointer to plugin-specific data.
 @end itemize
 
-For the PLUGIN_PASS_MANAGER_SETUP, PLUGIN_INFO,
PLUGIN_REGISTER_GGC_ROOTS
-and PLUGIN_REGISTER_GGC_CACHES pseudo-events the @code{callback} should
be
-null, and the @code{user_data} is specific.
+For the @i{PLUGIN_PASS_MANAGER_SETUP}, @i{PLUGIN_INFO},
+@i{PLUGIN_REGISTER_GGC_ROOTS} and @i{PLUGIN_REGISTER_GGC_CACHES}
+pseudo-events the @code{callback} should be null, and the
+@code{user_data} is specific.
 
-When the PLUGIN_PRAGMAS event is triggered (with a null
-pointer as data from GCC), plugins may register their own pragmas
-using functions like @code{c_register_pragma} or
-@code{c_register_pragma_with_expansion}.
+When the @i{PLUGIN_PRAGMAS} event is triggered (with a null pointer as
+data from GCC), plugins may register their own pragmas.  Notice that
+pragmas are not available from @file{lto1}, so plugins used with
+@code{-flto} option to GCC during link-time optimization cannot use
+pragmas and do not even see functions like @code{c_register_pragma} or
+@code{pragma_lex}.
 
+The @i{PLUGIN_INCLUDE_FILE} event, with a @code{const char*} file path
as
+GCC data, is triggered for processing of @code{#include} or
+@code{#line} directives.
+
+The @i{PLUGIN_FINISH} event is the last time that plugins can call GCC
+functions, notably emit diagnostics with @code{warning}, @code{error}
+etc.
+
+
 @node Plugins pass
 @section Interacting with the pass manager
 
@@ -376,10 +392,13 @@
 @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.
+The @i{PLUGIN_PRAGMAS} callback is called once during pragmas
+registration. Use the @code{c_register_pragma},
+@code{c_register_pragma_with_data},
+@code{c_register_pragma_with_expansion},
+@code{c_register_pragma_with_expansion_and_data} functions to register
+custom pragmas and their handlers (which often want to call
+@code{pragma_lex}) from @file{c-family/c-pragma.h}.
 
 @smallexample
 /* Plugin callback called during pragmas registration. Registered with
@@ -397,7 +416,15 @@
 It is suggested to pass @code{"GCCPLUGIN"} (or a short name identifying
 your plugin) as the ``space'' argument of your pragma.
 
+Pragmas registered with @code{c_register_pragma_with_expansion} or
+@code{c_register_pragma_with_expansion_and_data} are allowing
+preprocessor expansions, like e.g.
 
+@smallexample
+#define NUMBER 10
+#pragma GCCPLUGIN foothreshold (NUMBER)
+@end smallexample
+
 @node Plugins recording
 @section Recording information about pass execution
 
#####

Ok for 4.9?

Regards

Re: Ping^3 GCC trunk 4.9: documentation patch on plugins

[Diego Novillo]

On Tue, Mar 18, 2014 at 2:12 AM, Basile Starynkevitch
<basile@starynkevitch.net> wrote:
> On Sat, 2014-03-08 at 11:15 +0100, Basile Starynkevitch wrote:
>> I am pinging again this documentation patch
>> http://gcc.gnu.org/ml/gcc-patches/2014-02/msg00074.html
>> (pinged at http://gcc.gnu.org/ml/gcc-patches/2014-02/msg01002.html on febµ.17th 2014)
> and also pinged at
> http://gcc.gnu.org/ml/gcc-patches/2014-03/msg00387.html on march 8th
> 2014

Apologies for the delay. Please feel free to include me for patches I
may be able to help with.

> #### gcc/ChangeLog entry
>
> 2014-03-18  Basile Starynkevitch  <basile@starynkevitch.net>
>
>         * doc/plugins.texi (Plugin callbacks): Mention
>         PLUGIN_INCLUDE_FILE.
>         Italicize plugin event names in description.  Explain that
>         PLUGIN_PRAGMAS has no sense for lto1. Explain
>         PLUGIN_INCLUDE_FILE.
>         Remind that no GCC functions should be called after
>         PLUGIN_FINISH.
>         Explain what pragmas with expansion are.
>
> #### the patch:
> Index: gcc/doc/plugins.texi
> ===================================================================
> --- gcc/doc/plugins.texi        (revision 207422)
> +++ gcc/doc/plugins.texi        (working copy)
> @@ -209,6 +209,10 @@
>    PLUGIN_EARLY_GIMPLE_PASSES_END,
>    /* Called when a pass is first instantiated.  */
>    PLUGIN_NEW_PASS,
> +/* Called when a file is #include-d or given thru #line directive.

s/given thru/given via the/

> +   Could happen many times.  The event data is the included file path,

s/Could/This could/

> +Pragmas registered with @code{c_register_pragma_with_expansion} or
> +@code{c_register_pragma_with_expansion_and_data} are allowing
> +preprocessor expansions, like e.g.

I can't parse the last bit: "... are allowing preprocessor expansions,
like e.g.".  Did you mean something like "support preprocessor
expansions. For example,"


Diego.

Re: Ping^3 GCC trunk 4.9: documentation patch on plugins

[Basile Starynkevitch]

[-- Attachment #1: Type: text/plain, Size: 1058 bytes --]

Hello Diego & all,

Here is a slightly improved patch to follow Diego's comments on 
http://gcc.gnu.org/ml/gcc-patches/2014-03/msg00863.html

(since Diego improved the wording extracted from comments 
in gcc/plugin.def I am also patching the comments in that file).

### gcc/Changelog entry
2014-03-18  Basile Starynkevitch  <basile@starynkevitch.net>
	* plugin.def: Improve comment for PLUGIN_INCLUDE_FILE.
	
	* doc/plugins.texi (Plugin callbacks): Mention
	PLUGIN_INCLUDE_FILE.
	Italicize plugin event names in description.  Explain that
	PLUGIN_PRAGMAS has no sense for lto1. Explain
	PLUGIN_INCLUDE_FILE.
	Remind that no GCC functions should be called after
	PLUGIN_FINISH.
	Explain what pragmas with expansion are.
####

the [improved] patch against trunk 208643 is attached. 

Ok for GCC trunk 4.9?

Cheers
-- 
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} ***

[-- Attachment #2: gcc-plugindoc-r208643.diff --]
[-- Type: text/x-diff, Size: 3966 bytes --]

Index: gcc/doc/plugins.texi
===================================================================
--- gcc/doc/plugins.texi	(revision 208643)
+++ gcc/doc/plugins.texi	(working copy)
@@ -209,6 +209,10 @@
   PLUGIN_EARLY_GIMPLE_PASSES_END,
   /* Called when a pass is first instantiated.  */
   PLUGIN_NEW_PASS,
+/* Called when a file is #include-d or given via the #line directive.
+   This could happen many times.  The event data is the included file path,
+   as a const char* pointer.  */
+  PLUGIN_INCLUDE_FILE,
 
   PLUGIN_EVENT_FIRST_DYNAMIC    /* Dummy event used for indexing callback
                                    array.  */
@@ -229,15 +233,27 @@
 @item @code{void *user_data}: Pointer to plugin-specific data.
 @end itemize
 
-For the PLUGIN_PASS_MANAGER_SETUP, PLUGIN_INFO, PLUGIN_REGISTER_GGC_ROOTS
-and PLUGIN_REGISTER_GGC_CACHES pseudo-events the @code{callback} should be
-null, and the @code{user_data} is specific.
+For the @i{PLUGIN_PASS_MANAGER_SETUP}, @i{PLUGIN_INFO},
+@i{PLUGIN_REGISTER_GGC_ROOTS} and @i{PLUGIN_REGISTER_GGC_CACHES}
+pseudo-events the @code{callback} should be null, and the
+@code{user_data} is specific.
 
-When the PLUGIN_PRAGMAS event is triggered (with a null
-pointer as data from GCC), plugins may register their own pragmas
-using functions like @code{c_register_pragma} or
-@code{c_register_pragma_with_expansion}.
+When the @i{PLUGIN_PRAGMAS} event is triggered (with a null pointer as
+data from GCC), plugins may register their own pragmas.  Notice that
+pragmas are not available from @file{lto1}, so plugins used with
+@code{-flto} option to GCC during link-time optimization cannot use
+pragmas and do not even see functions like @code{c_register_pragma} or
+@code{pragma_lex}.
 
+The @i{PLUGIN_INCLUDE_FILE} event, with a @code{const char*} file path as
+GCC data, is triggered for processing of @code{#include} or
+@code{#line} directives.
+
+The @i{PLUGIN_FINISH} event is the last time that plugins can call GCC
+functions, notably emit diagnostics with @code{warning}, @code{error}
+etc.
+
+
 @node Plugins pass
 @section Interacting with the pass manager
 
@@ -376,10 +392,13 @@
 @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.
+The @i{PLUGIN_PRAGMAS} callback is called once during pragmas
+registration. Use the @code{c_register_pragma},
+@code{c_register_pragma_with_data},
+@code{c_register_pragma_with_expansion},
+@code{c_register_pragma_with_expansion_and_data} functions to register
+custom pragmas and their handlers (which often want to call
+@code{pragma_lex}) from @file{c-family/c-pragma.h}.
 
 @smallexample
 /* Plugin callback called during pragmas registration. Registered with
@@ -397,7 +416,15 @@
 It is suggested to pass @code{"GCCPLUGIN"} (or a short name identifying
 your plugin) as the ``space'' argument of your pragma.
 
+Pragmas registered with @code{c_register_pragma_with_expansion} or
+@code{c_register_pragma_with_expansion_and_data} are supporting
+preprocessor expansions. For an example of using such a pragma:
 
+@smallexample
+#define NUMBER 10
+#pragma GCCPLUGIN foothreshold (NUMBER)
+@end smallexample
+
 @node Plugins recording
 @section Recording information about pass execution
 
Index: gcc/plugin.def
===================================================================
--- gcc/plugin.def	(revision 208643)
+++ gcc/plugin.def	(working copy)
@@ -92,8 +92,8 @@
 /* Called when a pass is first instantiated.  */
 DEFEVENT (PLUGIN_NEW_PASS)
 
-/* Called when a file is #include-d or given thru #line directive.
-   Could happen many times.  The event data is the included file path,
+/* Called when a file is #include-d or given via the #line directive.
+   this could happen many times.  The event data is the included file path,
    as a const char* pointer.  */
 DEFEVENT (PLUGIN_INCLUDE_FILE)
 

Re: Ping^3 GCC trunk 4.9: documentation patch on plugins

[Diego Novillo]

OK with:

+Pragmas registered with @code{c_register_pragma_with_expansion} or
+@code{c_register_pragma_with_expansion_and_data} are supporting
+preprocessor expansions. For an example of using such a pragma:

s/are supporting/support/
s/For an example of using such a pragma/For example/


Diego.

Re: Ping^3 GCC trunk 4.9: documentation patch on plugins

[Basile Starynkevitch]

On Tue, 2014-03-18 at 08:53 -0400, Diego Novillo wrote:
> OK with:
> 
> +Pragmas registered with @code{c_register_pragma_with_expansion} or
> +@code{c_register_pragma_with_expansion_and_data} are supporting
> +preprocessor expansions. For an example of using such a pragma:
> 
> s/are supporting/support/
> s/For an example of using such a pragma/For example/
> 

Thanks for the review.
Committed revision 208660.

-- 
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 mine, sont seulement les miennes} ***