From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 103538 invoked by alias); 4 Nov 2015 23:52:25 -0000 Mailing-List: contact gcc-patches-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Id: List-Archive: List-Post: List-Help: Sender: gcc-patches-owner@gcc.gnu.org Received: (qmail 103473 invoked by uid 89); 4 Nov 2015 23:52:25 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-0.7 required=5.0 tests=AWL,BAYES_50,FREEMAIL_FROM,KAM_ASCII_DIVIDERS,RCVD_IN_DNSWL_LOW,SPF_PASS autolearn=no version=3.3.2 X-HELO: mail-qk0-f175.google.com Received: from mail-qk0-f175.google.com (HELO mail-qk0-f175.google.com) (209.85.220.175) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with (AES128-GCM-SHA256 encrypted) ESMTPS; Wed, 04 Nov 2015 23:52:23 +0000 Received: by qkas77 with SMTP id s77so23162483qka.0 for ; Wed, 04 Nov 2015 15:52:21 -0800 (PST) X-Received: by 10.55.78.204 with SMTP id c195mr4284473qkb.69.1446681140921; Wed, 04 Nov 2015 15:52:20 -0800 (PST) Received: from [192.168.0.26] (97-124-162-152.hlrn.qwest.net. [97.124.162.152]) by smtp.gmail.com with ESMTPSA id m23sm956599qkh.46.2015.11.04.15.52.19 (version=TLSv1.2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Wed, 04 Nov 2015 15:52:19 -0800 (PST) Message-ID: <563A9A31.5060306@gmail.com> Date: Wed, 04 Nov 2015 23:52:00 -0000 From: Martin Sebor User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:31.0) Gecko/20100101 Thunderbird/31.4.0 MIME-Version: 1.0 To: Alexander Monakov CC: Gcc Patch List Subject: Re: [PATCH] clarify documentation of -Q --help=optimizers References: <56299713.6040204@gmail.com> <562997A9.3090203@gmail.com> In-Reply-To: Content-Type: multipart/mixed; boundary="------------020307010609060300000706" X-IsSubscribed: yes X-SW-Source: 2015-11/txt/msg00411.txt.bz2 This is a multi-part message in MIME format. --------------020307010609060300000706 Content-Type: text/plain; charset=windows-1252; format=flowed Content-Transfer-Encoding: 7bit Content-length: 2499 On 11/03/2015 03:19 AM, Alexander Monakov wrote: > On Thu, 22 Oct 2015, Martin Sebor wrote: > >> [Sending to the right list this time] >> >> The documentation of the -Q --help=optimizers options leads some >> to expect that when options are reported as enabled imply the >> corresponding optimization will take place. (See the following >> question on gcc-help: >> https://gcc.gnu.org/ml/gcc-help/2015-10/msg00133.html) >> >> The patch below tries to make it clear that that's not always >> the case. > > Hi, > > The issue is due to optimization passes being skipped at -O0, and yet > corresponding optimization options not explicitely disabled. The effect of -O > is an old source of confusion, and now the intro to "Optimization Options" > says, > > Most optimizations are only enabled if an -O level is set on the command > line. Otherwise they are disabled, even if individual optimization flags > are specified. > > (added with this patch: > https://gcc.gnu.org/ml/gcc-patches/2009-10/msg00739.html ) Thanks for the reference! Despite the improvement, this continues to be a recurring problem. Users tend to miss the added text, maybe because it's on a different HTML page than the --help option. That certainly seemed to be the case in this post: https://gcc.gnu.org/ml/gcc-help/2015-10/msg00135.html It's also possible that it's because the caveat is mentioned in a context that doesn't match their use case. In the originally referenced thread, the user wasn't looking to enable additional optimizations. Rather, they were trying to see what (if any) optimizations are enabled by default, with -O0. > > As we observe, it's not visible enough, and I'm not sure saying that again in > the documentation (in a different section) is a good way to go. Maybe we'd > warn for attempts to enable optimizations at -O0, but that's not trivial. > Perhaps go with Richard's suggestion in the end of this mail ("Thus, at the > end of --help-optimizers print ...")? > https://gcc.gnu.org/ml/gcc-patches/2012-05/msg00113.html Improving the compiler output is a good idea. The attached patch prints "[disabled by -O0]" instead of "[enabled]" when an optimization option is enabled by default but when optimization (i.e., -O1 or greater) is not enabled. The patch also further clarifies the wording in the documentation to help users avoid falling into the trap of assuming, based on an incomplete reading of the manual, that some optimizations are performed even at -O0. Martin --------------020307010609060300000706 Content-Type: text/x-patch; name="gcc-help-optimizers.patch" Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename="gcc-help-optimizers.patch" Content-length: 4805 gcc/ChangeLog: 2015-11-04 Martin Sebor * opts.c (print_filtered_help): Indicate when an optimization option is disabled as a result of -O0. * doc/invoke.texi: Further clarify the effect of -O options on individual optimization options. gcc/testsuite/ChangeLog: 2015-11-04 Martin Sebor * testsuite/gcc.misc-tests/help.exp: Verify that optimization options are printed as disabled when -O0 is specified and enabled otherwise. Index: doc/invoke.texi =================================================================== --- doc/invoke.texi (revision 229716) +++ doc/invoke.texi (working copy) @@ -1509,6 +1509,14 @@ disabled or set to a specific value (assuming that the compiler knows this at the point where the @option{--help=} option is used). +It's important to remember that when a given optimization option is +enabled, either explicitly on the command line or implicitly, whether +or not the optimization it controls will be performed during an +invocation of the compiler may depend on other options, most commonly +one of the @option{-O} options. This is because many options control +various finer aspects of other more general optimizations that must +be enabled in order for the former option to have any effect. + Here is a truncated example from the ARM port of @command{gcc}: @smallexample @@ -1524,7 +1532,7 @@ are enabled at @option{-O2} by using: @smallexample --Q -O2 --help=optimizers + % gcc -Q -O2 --help=optimizers @end smallexample Alternatively you can discover which binary optimizations are enabled @@ -1531,11 +1539,22 @@ by @option{-O3} by using: @smallexample -gcc -c -Q -O3 --help=optimizers > /tmp/O3-opts -gcc -c -Q -O2 --help=optimizers > /tmp/O2-opts -diff /tmp/O2-opts /tmp/O3-opts | grep enabled + % gcc -c -Q -O3 --help=optimizers > /tmp/O3-opts + % gcc -c -Q -O2 --help=optimizers > /tmp/O2-opts + % diff /tmp/O2-opts /tmp/O3-opts | grep enabled @end smallexample +Finally, the following example shows the difference in output for +an option that, while technically enabled, is disabled as a consequence +of the implicit @option{-O0} option, and for one that is disabled by +default. This distinction is typically only of interest to GCC developers. +@smallexample + % gcc -Q --help=optimizers + The following options control optimizations: + -faggressive-loop-optimizations [disabled by -O0] + -falign-functions [disabled] +@end smallexample + @item -no-canonical-prefixes @opindex no-canonical-prefixes Do not expand any symbolic links, resolve references to @samp{/../} @@ -7678,9 +7697,9 @@ Not all optimizations are controlled directly by a flag. Only optimizations that have a flag are listed in this section. -Most optimizations are only enabled if an @option{-O} level is set on -the command line. Otherwise they are disabled, even if individual -optimization flags are specified. +Most optimizations are only performed when an @option{-O} option other +than @option{-O0} is specified on the command line. Otherwise they are +not performed, even if individual optimization flags are specified. Depending on the target and how GCC was configured, a slightly different set of optimizations may be enabled at each @option{-O} level than Index: opts.c =================================================================== --- opts.c (revision 229716) +++ opts.c (working copy) @@ -1190,6 +1190,15 @@ sprintf (new_help + strlen (new_help), "%#x", * (int *) flag_var); } + else if (option->flags & CL_OPTIMIZATION && !optimize) + { + /* Many options controlling optimization are enabled + but ineffective at -O0. Make that clear in the output + to avoid misleading users to expect that the respective + optimizations may take place. */ + strcat (new_help, option_enabled (i, opts) + ? _("[disabled by -O0]") : _("[disabled]")); + } else strcat (new_help, option_enabled (i, opts) ? _("[enabled]") : _("[disabled]")); Index: testsuite/gcc.misc-tests/help.exp =================================================================== --- testsuite/gcc.misc-tests/help.exp (revision 229716) +++ testsuite/gcc.misc-tests/help.exp (working copy) @@ -89,6 +89,18 @@ -O } "" "" +# Verify that options that are enabled by default but ineffective +# without -O0 are printed as "disabled by -O0" when -O0 is specified, +# and as "enabled" otherwise. +check_for_options c "-Q -O0 --help=optimizers" { +-O +-finline[^-][^\n]*disabled by -O0 +} "" "" +check_for_options c "-Q -O1 --help=optimizers" { +-O +-finline[^-][^\n]*enabled +} "" "" + # Ensure PR 37805 is fixed. # Specify patterns (arguments 3 and later) that match option names # at the beginning of the line and not when they are referenced by --------------020307010609060300000706--