[PATCH] Document -fdump-tree-vect option

[PATCH] Document -fdump-tree-vect option

[Jonathan Wakely]

[-- Attachment #1: Type: text/plain, Size: 250 bytes --]

This adds an item to the list of options for the -fdump-tree option,
because we show an example using 'vect' but don't document it.

OK for trunk?

Is there any logic to the order of those options? Would it makes sense
to order them alphabetically?


[-- Attachment #2: patch.txt --]
[-- Type: text/x-patch, Size: 1247 bytes --]

diff --git a/gcc/ChangeLog b/gcc/ChangeLog
index 649e2e8a303..491e8f0c694 100644
--- a/gcc/ChangeLog
+++ b/gcc/ChangeLog
@@ -1,3 +1,7 @@
+2017-10-13  Jonathan Wakely  <jwakely@redhat.com>
+
+	* doc/invoke.texi (-fdump-tree): Document 'vect' option.
+
 2017-10-13  Richard Biener  <rguenther@suse.de>
 
 	* graphite-isl-ast-to-gimple.c
diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index 4e7dfb33c31..0ff05445143 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -13323,7 +13323,7 @@ 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
+following options are available:
 
 @table @samp
 @item address
@@ -13386,6 +13386,8 @@ passes).
 @item note
 Enable other detailed optimization information (only available in
 certain passes).
+@item vect
+Enable showing vectorization 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

Re: [PATCH] Document -fdump-tree-vect option

[Sandra Loosemore]

On 10/13/2017 06:35 AM, Jonathan Wakely wrote:
> This adds an item to the list of options for the -fdump-tree option,
> because we show an example using 'vect' but don't document it.
>
> OK for trunk?

No, I think this patch is addressing an imaginary bug.  I see no "vect" 
option listed in the dump_options array in dumpfile.c.

I think this is the example in question:

@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.

I think the "vect" in this example is part of the pass name to be 
dumped, not an option modifying the dump output.  E.g. this is explicit 
in an older version of the GCC manual

https://gcc.gnu.org/onlinedocs/gcc-4.8.5/gcc/Debugging-Options.html#Debugging-Options

which includes the example AND documents "vect" as one of the tree dumps 
you can ask for.  The current version of this documentation doesn't 
explicitly list all the tree dumps any more, but GCC does still accept 
-fdump-tree-vect.

> Is there any logic to the order of those options? Would it makes sense
> to order them alphabetically?

My advice would be to move the =filename stuff out of the table (it's 
not really an option like the others) and refactor it into a paragraph 
before the option discussion, and in the table list "all" and "optall" 
first and then alphabetize the remaining entries (and make sure 
everything in the dump_options array is documented).

-Sandra

Re: [PATCH] Document -fdump-tree-vect option

[Jonathan Wakely]

On 13/10/17 14:06 -0600, Sandra Loosemore wrote:
>On 10/13/2017 06:35 AM, Jonathan Wakely wrote:
>>This adds an item to the list of options for the -fdump-tree option,
>>because we show an example using 'vect' but don't document it.
>>
>>OK for trunk?
>
>No, I think this patch is addressing an imaginary bug.  I see no 
>"vect" option listed in the dump_options array in dumpfile.c.
>
>I think this is the example in question:
>
>@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.
>
>I think the "vect" in this example is part of the pass name to be 
>dumped, not an option modifying the dump output.  E.g. this is 
>explicit in an older version of the GCC manual
>
>https://gcc.gnu.org/onlinedocs/gcc-4.8.5/gcc/Debugging-Options.html#Debugging-Options
>
>which includes the example AND documents "vect" as one of the tree 
>dumps you can ask for.  The current version of this documentation 
>doesn't explicitly list all the tree dumps any more, but GCC does 
>still accept -fdump-tree-vect.

Yes, I think I just misunderstood how this option works.

>>Is there any logic to the order of those options? Would it makes sense
>>to order them alphabetically?
>
>My advice would be to move the =filename stuff out of the table (it's 
>not really an option like the others) and refactor it into a paragraph 
>before the option discussion, and in the table list "all" and "optall" 
>first and then alphabetize the remaining entries (and make sure 
>everything in the dump_options array is documented).

I'll leave that to somebody who understands it.