As discussed in bug 32003 - Undocumented -fdump-tree options, rather
than duplicating the same boiler-plate text for each of the dozens
(138 by my count) of undocumented passes, the attached patch removes
the pass-specific -fdump-tree- options replacing them with a list of
generic steps to determine the full list of such options and the names
of the dump files for each.
The bug only talks about -fdump-tree- options so the attached patch
only tackles those and leaves the -fdump-rtl- options for another
time.
Martin
PR middle-end/32003 - Undocumented -fdump-tree options
gcc/ChangeLog:
PR middle-end/32003
* doc/invoke.texi (-fdump-rtl-): Remove pass-specific options from
index.
(-fdump-tree-@var): Add to index and document how to come up
with pass-specific option and dump file names.
(-fdump-passes): Clarify where to look for output.
diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index 4b13aeb..75b6e3e 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -543,30 +543,9 @@ Objective-C and Objective-C++ Dialects}.
-fdump-passes @gol
-fdump-rtl-@var{pass} -fdump-rtl-@var{pass}=@var{filename} @gol
-fdump-statistics @gol
--fdump-tree-all @gol
--fdump-tree-original@r{[}-@var{n}@r{]} @gol
--fdump-tree-optimized@r{[}-@var{n}@r{]} @gol
--fdump-tree-cfg -fdump-tree-alias @gol
--fdump-tree-ch @gol
--fdump-tree-ssa@r{[}-@var{n}@r{]} -fdump-tree-pre@r{[}-@var{n}@r{]} @gol
--fdump-tree-ccp@r{[}-@var{n}@r{]} -fdump-tree-dce@r{[}-@var{n}@r{]} @gol
--fdump-tree-gimple@r{[}-raw@r{]} @gol
--fdump-tree-dom@r{[}-@var{n}@r{]} @gol
--fdump-tree-dse@r{[}-@var{n}@r{]} @gol
--fdump-tree-phiprop@r{[}-@var{n}@r{]} @gol
--fdump-tree-phiopt@r{[}-@var{n}@r{]} @gol
--fdump-tree-backprop@r{[}-@var{n}@r{]} @gol
--fdump-tree-forwprop@r{[}-@var{n}@r{]} @gol
--fdump-tree-nrv -fdump-tree-vect @gol
--fdump-tree-sink @gol
--fdump-tree-sra@r{[}-@var{n}@r{]} @gol
--fdump-tree-forwprop@r{[}-@var{n}@r{]} @gol
--fdump-tree-fre@r{[}-@var{n}@r{]} @gol
--fdump-tree-vtable-verify @gol
--fdump-tree-vrp@r{[}-@var{n}@r{]} @gol
--fdump-tree-split-paths@r{[}-@var{n}@r{]} @gol
--fdump-tree-storeccp@r{[}-@var{n}@r{]} @gol
--fdump-final-insns=@var{file} @gol
+-fdump-tree-@var{switch} @gol
+-fdump-tree-@var{switch}-@var{options} @gol
+-fdump-tree-@var{switch}-@var{options}=@var{filename} @gol
-fcompare-debug@r{[}=@var{opts}@r{]} -fcompare-debug-second @gol
-fenable-@var{kind}-@var{pass} @gol
-fenable-@var{kind}-@var{pass}=@var{range-list} @gol
@@ -12971,8 +12950,8 @@ Dump after function inlining.
@item -fdump-passes
@opindex fdump-passes
-Dump the list of optimization passes that are turned on and off by
-the current command-line options.
+Print on @file{stderr} the list of optimization passes that are turned
+on and off by the current command-line options.
@item -fdump-statistics-@var{option}
@opindex fdump-statistics
@@ -13069,7 +13048,7 @@ example,
@smallexample
gcc -O2 -ftree-vectorize -fdump-tree-vect-blocks=foo.dump
- -fdump-tree-pre=stderr file.c
+ -fdump-tree-pre=/dev/stderr file.c
@end smallexample
outputs vectorizer dump into @file{foo.dump}, while the PRE dump is
@@ -13077,11 +13056,6 @@ 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 split-paths
-@opindex fdump-tree-split-paths
-Dump each function after splitting paths to loop backedges. The file
-name is made by appending @file{.split-paths} to the source file name.
-
@item all
Turn on all options, except @option{raw}, @option{slim}, @option{verbose}
and @option{lineno}.
@@ -13091,148 +13065,33 @@ Turn on all optimization options, i.e., @option{optimized},
@option{missed}, and @option{note}.
@end table
-The following tree dumps are possible:
-@table @samp
-
-@item original
-@opindex fdump-tree-original
-Dump before any tree based optimization, to @file{@var{file}.original}.
-
-@item optimized
-@opindex fdump-tree-optimized
-Dump after all tree based optimization, to @file{@var{file}.optimized}.
-
-@item gimple
-@opindex fdump-tree-gimple
-Dump each function before and after the gimplification pass to a file. The
-file name is made by appending @file{.gimple} to the source file name.
-
-@item cfg
-@opindex fdump-tree-cfg
-Dump the control flow graph of each function to a file. The file name is
-made by appending @file{.cfg} to the source file name.
-
-@item ch
-@opindex fdump-tree-ch
-Dump each function after copying loop headers. The file name is made by
-appending @file{.ch} to the source file name.
-
-@item ssa
-@opindex fdump-tree-ssa
-Dump SSA related information to a file. The file name is made by appending
-@file{.ssa} to the source file name.
-
-@item alias
-@opindex fdump-tree-alias
-Dump aliasing information for each function. The file name is made by
-appending @file{.alias} to the source file name.
-
-@item ccp
-@opindex fdump-tree-ccp
-Dump each function after CCP@. The file name is made by appending
-@file{.ccp} to the source file name.
-
-@item storeccp
-@opindex fdump-tree-storeccp
-Dump each function after STORE-CCP@. The file name is made by appending
-@file{.storeccp} to the source file name.
-
-@item pre
-@opindex fdump-tree-pre
-Dump trees after partial redundancy elimination and/or code hoisting.
-The file name is made by appending @file{.pre} to the source file name.
-
-@item fre
-@opindex fdump-tree-fre
-Dump trees after full redundancy elimination. The file name is made
-by appending @file{.fre} to the source file name.
-
-@item copyprop
-@opindex fdump-tree-copyprop
-Dump trees after copy propagation. The file name is made
-by appending @file{.copyprop} to the source file name.
-
-@item store_copyprop
-@opindex fdump-tree-store_copyprop
-Dump trees after store copy-propagation. The file name is made
-by appending @file{.store_copyprop} to the source file name.
-
-@item dce
-@opindex fdump-tree-dce
-Dump each function after dead code elimination. The file name is made by
-appending @file{.dce} to the source file name.
-
-@item sra
-@opindex fdump-tree-sra
-Dump each function after performing scalar replacement of aggregates. The
-file name is made by appending @file{.sra} to the source file name.
-
-@item sink
-@opindex fdump-tree-sink
-Dump each function after performing code sinking. The file name is made
-by appending @file{.sink} to the source file name.
-
-@item dom
-@opindex fdump-tree-dom
-Dump each function after applying dominator tree optimizations. The file
-name is made by appending @file{.dom} to the source file name.
-
-@item dse
-@opindex fdump-tree-dse
-Dump each function after applying dead store elimination. The file
-name is made by appending @file{.dse} to the source file name.
-
-@item phiopt
-@opindex fdump-tree-phiopt
-Dump each function after optimizing PHI nodes into straightline code. The file
-name is made by appending @file{.phiopt} to the source file name.
-
-@item backprop
-@opindex fdump-tree-backprop
-Dump each function after back-propagating use information up the definition
-chain. The file name is made by appending @file{.backprop} to the
-source file name.
-
-@item forwprop
-@opindex fdump-tree-forwprop
-Dump each function after forward propagating single use variables. The file
-name is made by appending @file{.forwprop} to the source file name.
-
-@item nrv
-@opindex fdump-tree-nrv
-Dump each function after applying the named return value optimization on
-generic trees. The file name is made by appending @file{.nrv} to the source
-file name.
-
-@item vect
-@opindex fdump-tree-vect
-Dump each function after applying vectorization of loops. The file name is
-made by appending @file{.vect} to the source file name.
-
-@item slp
-@opindex fdump-tree-slp
-Dump each function after applying vectorization of basic blocks. The file name
-is made by appending @file{.slp} to the source file name.
-
-@item vrp
-@opindex fdump-tree-vrp
-Dump each function after Value Range Propagation (VRP). The file name
-is made by appending @file{.vrp} to the source file name.
+The determine what tree dumps are available or find the dump for a pass
+of interest follow the steps below.
-@item early vrp
-@opindex fdump-tree-evrp
-Dump each function after Early Value Range Propagation (EVRP). The file name
-is made by appending @file{.evrp} to the source file name.
-
-@item oaccdevlow
-@opindex fdump-tree-oaccdevlow
-Dump each function after applying device-specific OpenACC transformations.
-The file name is made by appending @file{.oaccdevlow} to the source file name.
-
-@item all
-@opindex fdump-tree-all
-Enable all the available tree dumps with the flags provided in this option.
-@end table
+@enumerate
+@item
+Invoke GCC with @option{-fdump-passes} and in the @file{stderr} output
+look for a code that corresponds to the pass you are interested in.
+For example, the codes @code{tree-evrp}, @code{tree-vrp1}, and
+@code{tree-vrp2} correspond to the three Value Range Propagation passes.
+The number at the end distinguishes distinct invocations of the same pass.
+@item
+To enable the creation of the dump file, append the pass code to
+the @option{-fdump-} option prefix and invoke GCC with it. For example,
+to enable the dump from the Early Value Range Propagation pass, invoke
+GCC with the @code{-fdump-tree-evrp} option. Optionally, you may
+specify the name of the dump file. If you don't specify one, GCC will
+create on as described below.
+@item
+Find the pass dump in a file whose name is composed of three components
+separated by a period: the name of the source file GCC was invoked to
+compile, a numeric suffix indicating the pass number followed by the
+letter @code{t} for tree passes (and the letter @code{r} for rtl passes),
+and finally the pass code. For example, the Early VRP pass dump might be
+in a file named @file{myfile.c.038t.evrp} in the current working
+directory. Note that the numeric codes need not be stable and may change
+from one version of GCC to another.
+@end enumerate
@item -fopt-info
@itemx -fopt-info-@var{options}
