allow '-' for stdout dump

Here's the patch to allow '-' as a synonym for 'stdout'.  It's easier to type, 
and a convention used elsewhere.

Also document the existing stdout/stderr selection along with the new behaviour?

ok for trunk?

nathan

On 04/26/2018 11:12 AM, Nathan Sidwell wrote:

> Index: doc/invoke.texi
> ===================================================================
> --- doc/invoke.texi	(revision 259680)
> +++ doc/invoke.texi	(working copy)
> @@ -13368,9 +13368,10 @@ Says to make debugging dumps during comp
>  @var{letters}.  This is used for debugging the RTL-based passes of the
>  compiler.  The file names for most of the dumps are made by appending
>  a pass number and a word to the @var{dumpname}, and the files are
> -created in the directory of the output file.  In case of
> -@option{=@var{filename}} option, the dump is output on the given file
> -instead of the pass numbered dump files.  Note that the pass number is
> +created in the directory of the output file.  Using a
> +@option{=@var{filename}} suffix overrides this default scheme.  You
> +can specify @code{stdout} or @code{-} to refer to standard output, and
> +@code{stderr} for standard error.  Note that the pass number is
>  assigned as passes are registered into the pass manager.  Most passes
>  are registered in the order that they will execute and for these passes
>  the number corresponds to the pass execution order.  However, passes

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:

- The 2 introductory sentences explaining what the option does.
- The default dump file name description.
- How to override it.

-Sandra

On Thu, Apr 26, 2018 at 7:12 PM, Nathan Sidwell <nathan@acm.org> wrote:
> Here's the patch to allow '-' as a synonym for 'stdout'.  It's easier to
> type, and a convention used elsewhere.
>
> Also document the existing stdout/stderr selection along with the new
> behaviour?
>
> ok for trunk?

OK for the dumpfile.c part.  Please iterate on the doc part with Sandra.

Richard.

> nathan
> --
> Nathan Sidwell

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?

nathan

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

On 04/28/2018 11:33 AM, Sandra Loosemore wrote:
> On 04/27/2018 07:12 AM, Nathan Sidwell wrote:

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

looks good, this is what I'm committing, thanks!

nathan