Re: [patch] allow '-' for stdout dump

[Sandra Loosemore <sandra at codesourcery dot com>]

On 04/27/2018 07:12 AM, Nathan Sidwell wrote:
> On 04/26/2018 01:31 PM, Sandra Loosemore wrote:
>
> > Hmmm, I'm not crazy about putting this material in the middle of a 
> > discussion about how the compiler comes up with its default dump file 
> > names.  How about splitting the existing paragraph into 3:
>
> Yeah, that documentation is rather a mess.  I tried rationalizing the 
> developer options into different subsections, but that quickly turned 
> into a rat hole. Here I've just pulled out the filename creation to an 
> earlier paragraph.
>
> WDYT? 
>
> Index: invoke.texi
> ===================================================================
> --- invoke.texi	(revision 259683)
> +++ invoke.texi	(working copy)
> @@ -13357,6 +13357,25 @@ configuration, such as where it searches
>  rarely need to use any of these options for ordinary compilation and
>  linking tasks.
>  
> +Many developer options control dump output, and may take an optional
> +@option{=@var{filename}} suffix.  If that is omitted, a default
> +filename is determined by appending a pass number & phase letter,
> +followed by the pass name to a @var{dumpname}.  The files are created
> +in the directory of the output file.  The @var{dumpname} is the name
> +of the output file, if explicitly specified and not an executable,
> +otherwise it is the source file name.  The pass number is determined
> +when a particular pass is registered with the compiler's pass manager.
> +Usually passes executed in the order of registration, so this number
> +corresponds to the pass execution order.  However, passes registered
> +by plugins, passes specific to compilation targets, or passes that are
> +otherwise registered after all the other passes are numbered higher
> +than a pass named "final", even if they are executed earlier.  The
> +phase letter is `i', `l', `r' or `t'.
> +
> +The default can be overridden by appending a @option{=@var{filename}}
> +suffix to the option.  You can specify @code{stdout} or @code{-} to
> +refer to standard output, and @code{stderr} for standard error.
> +
>  @table @gcctabopt
>  
>  @item -d@var{letters}

Hmmm, I'd like to wordsmith this a bit and clean up the markup, etc. 
How about this?

Many developer options that cause GCC to dump output to a file take an 
optional @samp{=@var{filename}} suffix.
You can specify @samp{stdout} or @samp{-} to dump to standard output, 
and @samp{stderr} for standard error.

If @samp{=@var{filename}} is omitted, a default dump file name is 
constructed by concatenating the base dump file name, a pass number, 
phase letter, and pass name.  The base dump file name is the name of 
output file produced by the compiler if explicitly specified and not an 
executable; otherwise it is the source file name.
The pass number is determined by the order passes are registered with 
the compiler's pass manager.
This is generally the same as the order of execution, but passes
registered by plugins, target-specific passes, or passes that are 
otherwise registered late are numbered higher than the pass named 
@samp{final}, even if they are executed earlier.
The phase letter is one of @samp{i} (inter-procedural analysis), 
@samp{l} (language-specific), @samp{r} (RTL), or @samp{t} (tree).
The files are created in the directory of the output file.

-Sandra