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 -- Nathan Sidwell
2018-04-27 Nathan Sidwell <nat...@acm.org> * dumpfile.c (dump_open): Allow '-' for stdout. * doc/invoke.texi (Developer Options): Document dump filename determination early. Document stdin/stdout selection. 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} @@ -13366,20 +13385,7 @@ linking tasks. @opindex fdump-rtl-@var{pass} Says to make debugging dumps during compilation at times specified by @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 -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 -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. @var{dumpname} is generated from the name of the output -file if explicitly specified and not an executable, otherwise it is -the basename of the source file. +compiler. Some @option{-d@var{letters}} switches have different meaning when @option{-E} is used for preprocessing. @xref{Preprocessor Options}, @@ -13767,15 +13773,11 @@ counters for each function compiled. @opindex fdump-tree-all @opindex fdump-tree Control the dumping at various stages of processing the intermediate -language tree to a file. The file name is generated by appending a -switch-specific suffix to the source file name, and the file is -created in the same directory as the output file. In case of -@option{=@var{filename}} option, the dump is output on the given file -instead of the auto named dump files. If the @samp{-@var{options}} -form is used, @var{options} is a list of @samp{-} separated options -which control the details of the dump. Not all options are applicable -to all dumps; those that are not meaningful are ignored. The -following options are available +language tree to a file. If the @samp{-@var{options}} form is used, +@var{options} is a list of @samp{-} separated options which control +the details of the dump. Not all options are applicable to all dumps; +those that are not meaningful are ignored. The following options are +available @table @samp @item address @@ -13838,26 +13840,9 @@ passes). @item note Enable other detailed optimization information (only available in certain passes). -@item =@var{filename} -Instead of an auto named dump file, output into the given file -name. The file names @file{stdout} and @file{stderr} are treated -specially and are considered already open standard streams. For -example, - -@smallexample -gcc -O2 -ftree-vectorize -fdump-tree-vect-blocks=foo.dump - -fdump-tree-pre=/dev/stderr file.c -@end smallexample - -outputs vectorizer dump into @file{foo.dump}, while the PRE dump is -output on to @file{stderr}. If two conflicting dump filenames are -given for the same pass, then the latter option overrides the earlier -one. - @item all Turn on all options, except @option{raw}, @option{slim}, @option{verbose} and @option{lineno}. - @item optall Turn on all optimization options, i.e., @option{optimized}, @option{missed}, and @option{note}.