From patchwork Sat Sep 11 19:59:28 2010 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: gengtype improvements for plugins, completed! patch 7/N [doc] Date: Sat, 11 Sep 2010 09:59:28 -0000 From: Basile Starynkevitch X-Patchwork-Id: 64529 Message-Id: <20100911195928.GA31368@hector.lesours> To: Basile Starynkevitch , gcc-patches@gcc.gnu.org Hello All, [join work by Basile Starynkevitch & Jeremie Salvucci] References: http://gcc.gnu.org/ml/gcc-patches/2010-08/msg02060.html http://gcc.gnu.org/ml/gcc-patches/2010-09/msg00616.html http://gcc.gnu.org/ml/gcc-patches/2010-09/msg00663.html http://gcc.gnu.org/ml/gcc-patches/2010-08/msg02063.html http://gcc.gnu.org/ml/gcc-patches/2010-08/msg02065.html http://gcc.gnu.org/ml/gcc-patches/2010-08/msg02068.html http://gcc.gnu.org/ml/gcc-patches/2010-09/msg00983.html http://gcc.gnu.org/ml/gcc-patches/2010-08/msg02069.html http://gcc.gnu.org/ml/gcc-patches/2010-09/msg01029.html The 7th and last part [doc] of our patch series "completed!" is a documentation patch. I added a few missing sentences about some GTY tags, and I documented imperfectly the new gengtype prorgram interface, in particular its gengtype state facility. Since I did not sent any patch on documentation, the difference is only on gty.texi and has been obtained with svn diff -x -p gcc/doc/gty.texi > ~/tmp/gengtype_patch_7_of_N__doc.diff You can apply it to the trunk 163987 or to the previous patch 6/N [wstate]. As usual, I am attaching for convenience the cumulated patches against trunk 163987 as a gzip file gengtype_patch_7_of_N__doc-cumulatedto07-trunrev-163987.diff.gz Jeremie did not write any documentation, so please blame (gently!) me for the english mistakes etc, and suggest better phrasing. #################### gcc/ChangeLog entry for documentation 2010-09-11 Basile Starynkevitch * gcc/doc/gty.texi: (Generating GGC code with gengtype): New node. (GTY Options): Documented that tag should be unique. Added ptr_alias documentation. (How to run the gengtype generator): New section. ################################################################ Comments are welcome. Cheers. Index: incr-gengtype-gcc/gcc/doc/gty.texi =================================================================== --- incr-gengtype-gcc/gcc/doc/gty.texi (revision 163987) +++ incr-gengtype-gcc/gcc/doc/gty.texi (working copy) @@ -69,6 +69,7 @@ These don't need to be marked. * GTY Options:: What goes inside a @code{GTY(())}. * GGC Roots:: Making global variables GGC roots. * Files:: How the generated files work. +* Generating GGC code with gengtype:: How to run the gengtype generator. * Invoking the garbage collector:: How to invoke the garbage collector. @end menu @@ -183,6 +184,7 @@ The value of the expression given by @code{desc} i each @code{tag} value, each of which should be different. If no @code{tag} is matched, the field marked with @code{default} is used if there is one, otherwise no field in the union will be marked. +A union field can have at most one @code{tag}. In the @code{desc} option, the ``current structure'' is the union that it discriminates. Use @code{%1} to mean the structure containing it. @@ -312,6 +314,12 @@ and the @var{from expression} returns the original the pointer. The pointer will be available using the @code{%h} escape. +@findex ptr_alias +@item ptr_alias (@var{type}) + +When applied to a type, @code{ptr_alias} indicates that the GTY-ed +type is an alias or synonym of the given @var{type}. + @findex chain_next @findex chain_prev @findex chain_circular @@ -472,12 +480,55 @@ somewhere. It will be called @file{gtype-@var{lan @var{lang} is the name of the subdirectory the language is contained in. Plugins can add additional root tables. Run the @code{gengtype} -utility in plugin mode as @code{gengtype -P pluginout.h @var{source-dir} -@var{file-list} @var{plugin*.c}} with your plugin files -@var{plugin*.c} using @code{GTY} to generate the @var{pluginout.h} file. -The GCC build tree is needed to be present in that mode. +utility in plugin mode as @code{gengtype -P @var{gt-pluginout.h} -r +@var{gtype.state} @var{plugin*.c}} with your plugin files +@var{plugin*.c} using @code{GTY} to generate the @var{gt-pluginout.h} +file. The @var{gtype.state} is usually in the plugin directory. +@node Generating GGC code with gengtype +@section How to run the gengtype generator. +@cindex garbage collector, generation, gengtype +@findex gengtype + +The @code{gengtype} utility (which may be installed as +@code{gcc-gengtype} or some other name on your system) is a C code +generator program. It generates suitable marking and type-walking C +routines for GGC. Generated GC marking routines ensure that every +live data is ultimately marked, so that GGC can delete, at the end of +its @code{ggc_collect} function, every non-marked data (which is +unreachable and dead). Generated PCH type-walking routines are used +for ``compilation'' of header files @var{*.h} into a @var{*.gch} +file. The @code{gengtype} utility is used when building GCC itself +from its source tree, and also for plugins dealing with their own +GTY-ed data. + +The @code{gengtype} utility is run once specially when compiling GCC +itself. It parses many GCC source files (mostly internal GCC headers +declaring @code{GTY}-ed types and internal GCC files declaring +@code{GTY}-ed variables). It saves its state in a persistent textual +file @file{gtype.state}. This file has a format tied to a particular +GCC release and configuration. This @file{gtype.state} file should be +parsed only by @code{gengtype} (of the same version which has +generated it). Following GNU usage, @code{gengtype} accepts the usual +@code{--version} or @code{-V} and @code{--help} arguments. It also +accepts @code{--verbose} or @code{-v} to show what it is doing, and +@code{--debug} or @code{-D} for debugging purposes. It may dump its +state in human readable form with @code{--dump} or @code{-d}. + +During GCC build process, a file @file{gtyp-input.list} is built and +contains a long list of files to be parsed. Then, @code{gengtype} is +run once to generate its state with @code{gengtype -S +@file{source-directory} -I @file{gtyp-input.list} -w +@file{gtype.state}}. Immediately after, it is re-run to read its just +generated state and generate @file{gt*.[ch]} files with @code{gengtype +-r @file{gtype.state}}. + +Plugin developers using @code{GTY} in their plugin source code should +run @code{gengtype -P @var{gt-pluginout.h} -r @file{gtype.state} +@var{plugin*.c}} + + @node Invoking the garbage collector @section How to invoke the garbage collector @cindex garbage collector, invocation