doc: properly describe --enable-checking behavior

This patch rewords the whole description to fix minor issues:
 - documents 'gimple' and 'types' checks,
 - clarifies what happens when option is used without '=list',
 - fixes inaccurate wrong wording about release snapshots,
 - describes that release checks can only de disabled explicitly.

gcc/ChangeLog:
	* doc/install.texi (--enable-checking): Properly document current
	behavior.
	(--enable-stage1-checking): Minor clarification about bootstrap.

diff --git a/gcc/ChangeLog b/gcc/ChangeLog
index 13f0356..3292b9f 100644 (file)
--- a/gcc/ChangeLog
+++ b/gcc/ChangeLog
@@ -1,3 +1,9 @@
+2020-02-24  Roman Zhuykov  <zhroma@ispras.ru>
+
+       * doc/install.texi (--enable-checking): Properly document current
+       behavior.
+       (--enable-stage1-checking): Minor clarification about bootstrap.
+
 2020-02-24  David Malcolm  <dmalcolm@redhat.com>
 
        PR analyzer/93032

diff --git a/gcc/doc/install.texi b/gcc/doc/install.texi
index 8ddebbb..09207cc 100644 (file)
--- a/gcc/doc/install.texi
+++ b/gcc/doc/install.texi
@@ -1839,41 +1839,48 @@ final releases.  The specific files which get @option{-Werror} are
 controlled by the Makefiles.
 
 @item --enable-checking
+@itemx --disable-checking
 @itemx --enable-checking=@var{list}
-When you specify this option, the compiler is built to perform internal
-consistency checks of the requested complexity.  This does not change the
-generated code, but adds error checking within the compiler.  This will
-slow down the compiler and may only work properly if you are building
-the compiler with GCC@.  This is @samp{yes,extra} by default when building
-from the source repository or snapshots, but @samp{release} for releases.  The default
-for building the stage1 compiler is @samp{yes}.  More control
-over the checks may be had by specifying @var{list}.  The categories of
-checks available are @samp{yes} (most common checks
-@samp{assert,misc,tree,gc,rtlflag,runtime}), @samp{no} (no checks at
-all), @samp{all} (all but @samp{valgrind}), @samp{release} (cheapest
-checks @samp{assert,runtime}) or @samp{none} (same as @samp{no}).
-Individual checks can be enabled with these flags @samp{assert},
-@samp{df}, @samp{fold}, @samp{gc}, @samp{gcac}, @samp{misc}, @samp{rtl},
-@samp{rtlflag}, @samp{runtime}, @samp{tree}, @samp{extra} and @samp{valgrind}.
-@samp{extra} adds for @samp{misc} checking extra checks that might affect
-code generation and should therefore not differ between stage1 and later
-stages.
-
-The @samp{valgrind} check requires the external @command{valgrind}
-simulator, available from @uref{http://valgrind.org/}.  The
-@samp{df}, @samp{rtl}, @samp{gcac} and @samp{valgrind} checks are very expensive.
-To disable all checking, @samp{--disable-checking} or
-@samp{--enable-checking=none} must be explicitly requested.  Disabling
-assertions will make the compiler and runtime slightly faster but
-increase the risk of undetected internal errors causing wrong code to be
-generated.
+This option controls performing internal consistency checks in the compiler.
+It does not change the generated code, but adds error checking of the
+requested complexity.  This slows down the compiler and may only work
+properly if you are building the compiler with GCC@.
+
+When the option is not specified, the active set of checks depends on context.
+Namely, bootstrap stage 1 defaults to @samp{--enable-checking=yes}, builds
+from release archives default to @samp{--enable-checking=release}, and
+otherwise @samp{--enable-checking=yes,extra} is used.  When the option is
+specified without a @var{list}, the result is the same as
+@samp{--enable-checking=yes}.  Likewise, @samp{--disable-checking} is
+equivalent to @samp{--enable-checking=no}.
+
+The categories of checks available in @var{list} are @samp{yes} (most common
+checks @samp{assert,misc,gc,gimple,rtlflag,runtime,tree,types}), @samp{no}
+(no checks at all), @samp{all} (all but @samp{valgrind}), @samp{release}
+(cheapest checks @samp{assert,runtime}) or @samp{none} (same as @samp{no}).
+@samp{release} checks are always on and to disable them
+@samp{--disable-checking} or @samp{--enable-checking=no[,<other checks>]}
+must be explicitly requested.  Disabling assertions makes the compiler and
+runtime slightly faster but increases the risk of undetected internal errors
+causing wrong code to be generated.
+
+Individual checks can be enabled with these flags: @samp{assert}, @samp{df},
+@samp{extra}, @samp{fold}, @samp{gc}, @samp{gcac}, @samp{gimple},
+@samp{misc}, @samp{rtl}, @samp{rtlflag}, @samp{runtime}, @samp{tree},
+@samp{types} and @samp{valgrind}.  @samp{extra} extends @samp{misc}
+checking with extra checks that might affect code generation and should
+therefore not differ between stage1 and later stages in bootstrap.
+
+The @samp{valgrind} check requires the external @command{valgrind} simulator,
+available from @uref{http://valgrind.org/}.  The @samp{df}, @samp{rtl},
+@samp{gcac} and @samp{valgrind} checks are very expensive.
 
 @item --disable-stage1-checking
 @itemx --enable-stage1-checking
 @itemx --enable-stage1-checking=@var{list}
-If no @option{--enable-checking} option is specified the stage1
-compiler will be built with @samp{yes} checking enabled, otherwise
-the stage1 checking flags are the same as specified by
+This option affects only bootstrap build.  If no @option{--enable-checking}
+option is specified the stage1 compiler is built with @samp{yes} checking
+enabled, otherwise the stage1 checking flags are the same as specified by
 @option{--enable-checking}.  To build the stage1 compiler with
 different checking options use @option{--enable-stage1-checking}.
 The list of checking options is the same as for @option{--enable-checking}.