From: Basile Starynkevitch <basile@starynkevitch.net>
To: gcc-patches@gcc.gnu.org
Subject: GCC trunk 4.9: documentation patch on plugins
Date: Mon, 03 Feb 2014 13:52:00 -0000 [thread overview]
Message-ID: <20140203135214.GA25755@ours.starynkevitch.net> (raw)
[-- 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
next reply other threads:[~2014-02-03 13:52 UTC|newest]
Thread overview: 8+ messages / expand[flat|nested] mbox.gz Atom feed top
2014-02-03 13:52 Basile Starynkevitch [this message]
2014-02-17 13:51 ` Ping " Basile Starynkevitch
2014-03-08 10:15 ` Ping^2 " Basile Starynkevitch
2014-03-18 8:16 ` Ping^3 " Basile Starynkevitch
2014-03-18 11:44 ` Diego Novillo
2014-03-18 12:32 ` Basile Starynkevitch
2014-03-18 13:08 ` Diego Novillo
2014-03-18 20:03 ` Basile Starynkevitch
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20140203135214.GA25755@ours.starynkevitch.net \
--to=basile@starynkevitch.net \
--cc=gcc-patches@gcc.gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).