From: Roman Zhuykov Date: Tue, 25 Feb 2020 07:15:49 +0000 (+0300) Subject: doc: properly describe --enable-checking behavior X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=267cca3d20139ecea6b023ef0d5767ecf703e93a;p=gcc.git 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 13f0356c9ae..3292b9f0842 100644 --- a/gcc/ChangeLog +++ b/gcc/ChangeLog @@ -1,3 +1,9 @@ +2020-02-24 Roman Zhuykov + + * doc/install.texi (--enable-checking): Properly document current + behavior. + (--enable-stage1-checking): Minor clarification about bootstrap. + 2020-02-24 David Malcolm PR analyzer/93032 diff --git a/gcc/doc/install.texi b/gcc/doc/install.texi index 8ddebbb6267..09207ccf1da 100644 --- 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[,]} +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}.