From patchwork Sat Mar 8 10:15:35 2014 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Basile Starynkevitch X-Patchwork-Id: 328173 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 64C182C00B3 for ; Sat, 8 Mar 2014 21:15:53 +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:cc:subject:message-id:references:mime-version :content-type:content-transfer-encoding:in-reply-to; q=dns; s= default; b=ncemkiffnWGgRCYKt2IqxX+u62DZOYJhy3bQtPRCzyTgIq2AhfP2M uVze0xfS9Dz43W4fQDX3E6NYltjggC9BPNnAV2mHKdhlIBl0OEo7GS6M6PEXPmsK KVOkSHltbLFbQcaBo+edU2MaSD0uOhveg2RiA/IAQsPhcEd2MRQqHA= 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:cc:subject:message-id:references:mime-version :content-type:content-transfer-encoding:in-reply-to; s=default; bh=V8wnvqrzXDHhJrSaCaxqvHVq08Y=; b=Mo369t1VZp3yRlQqyg/xiP3KThzY TezrEpUSHs+mzi//ixsHOa/+ltydR+QUyRsb9N5vZO4thAwuFiUKOofFjeHZBNvF 4N9yUZdpxvmpUsUf3iArwZoM7NdWKE6MXdK9hiy60vuwGAECLPs508xOXjGZksRN DHbKprOZjwj84i0= Received: (qmail 8204 invoked by alias); 8 Mar 2014 10:15:46 -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 8194 invoked by uid 89); 8 Mar 2014 10:15:45 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-1.5 required=5.0 tests=AWL, BAYES_00, T_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; Sat, 08 Mar 2014 10:15:44 +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 1WMEI8-0002k5-VX; Sat, 08 Mar 2014 11:15:41 +0100 Received: from basile18 by hector.lesours with local (Exim 4.82) (envelope-from ) id 1WMEI3-0003uX-Is; Sat, 08 Mar 2014 11:15:35 +0100 Date: Sat, 8 Mar 2014 11:15:35 +0100 From: Basile Starynkevitch To: Basile Starynkevitch Cc: gcc-patches@gcc.gnu.org Subject: Ping^2 GCC trunk 4.9: documentation patch on plugins Message-ID: <20140308101535.GA14958@ours.starynkevitch.net> References: <20140203135214.GA25755@ours.starynkevitch.net> <20140217135110.GA19358@ours.starynkevitch.net> MIME-Version: 1.0 Content-Disposition: inline In-Reply-To: <20140217135110.GA19358@ours.starynkevitch.net> User-Agent: Mutt/1.5.22 (2013-10-16) X-IsSubscribed: yes 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 * 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: ##### 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