From patchwork Mon Feb 3 13:52:14 2014 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Basile Starynkevitch X-Patchwork-Id: 316158 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from sourceware.org (server1.sourceware.org [209.132.180.131]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 3CA292C0078 for ; Tue, 4 Feb 2014 00:52:32 +1100 (EST) DomainKey-Signature: a=rsa-sha1; c=nofws; d=gcc.gnu.org; h=list-id :list-unsubscribe:list-archive:list-post:list-help:sender:date :from:to:subject:message-id:mime-version:content-type; q=dns; s= default; b=HASx13gmWzylxsF1yBBQACK+bebbpTPcn/KXuHyNZ4ec48JizRPFH s7DqBUaakVz39B7NJNc+A94hZL+CO2Lr1tRllFmMAWazPbtAjCGb930Cehdts9e/ gp1Qwpre11DMWlXXpVjFio1f6ZRocxsS61fkmhTteHC9XLA75UiKSU= DKIM-Signature: v=1; a=rsa-sha1; c=relaxed; d=gcc.gnu.org; h=list-id :list-unsubscribe:list-archive:list-post:list-help:sender:date :from:to:subject:message-id:mime-version:content-type; s= default; bh=3AgEN3bzAbXP6ckuTisaTGUkcQo=; b=CSW537hM4aNbvUWFYMAh qscX6ROaich08nWgRReyVZQsCHUcego1avGlGDTZAAJplkxkkNKY1t14440qCMye tE5SmuDthUNhBQ1cczm8oYV9YKILURZe5VLhp4kVz1RBbmGuyKhnArLd82atKuXo vDy4etvwQpMJK4d0G9uDtWU= Received: (qmail 3106 invoked by alias); 3 Feb 2014 13:52:25 -0000 Mailing-List: contact gcc-patches-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Archive: List-Post: List-Help: Sender: gcc-patches-owner@gcc.gnu.org Delivered-To: mailing list gcc-patches@gcc.gnu.org Received: (qmail 3097 invoked by uid 89); 3 Feb 2014 13:52:24 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-1.8 required=5.0 tests=AWL, BAYES_00, RP_MATCHES_RCVD autolearn=ham version=3.3.2 X-HELO: ovh.starynkevitch.net Received: from ovh.starynkevitch.net (HELO ovh.starynkevitch.net) (46.105.17.220) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with (AES256-SHA encrypted) ESMTPS; Mon, 03 Feb 2014 13:52:22 +0000 Received: from ours.starynkevitch.net ([213.41.244.95] helo=hector.lesours) by ovh.starynkevitch.net with esmtp (Exim 4.76) (envelope-from ) id 1WAJwh-0005Ty-KX for gcc-patches@gcc.gnu.org; Mon, 03 Feb 2014 14:52:19 +0100 Received: from basile18 by hector.lesours with local (Exim 4.82) (envelope-from ) id 1WAJwc-0006j3-EH for gcc-patches@gcc.gnu.org; Mon, 03 Feb 2014 14:52:14 +0100 Date: Mon, 3 Feb 2014 14:52:14 +0100 From: Basile Starynkevitch To: gcc-patches@gcc.gnu.org Subject: GCC trunk 4.9: documentation patch on plugins Message-ID: <20140203135214.GA25755@ours.starynkevitch.net> MIME-Version: 1.0 Content-Disposition: inline User-Agent: Mutt/1.5.21 (2010-09-15) X-IsSubscribed: yes 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 * 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 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