[patch, docu] Update -ffunction-sections docs (was: Re: [PING, patch, libgfortran] Build with -ffunction-sections -fdata-sections)

["Ulrich Weigand" <uweigand at de dot ibm dot com>]

Steve Kargl wrote:
> On Thu, Apr 16, 2009 at 02:55:11PM +0200, Ulrich Weigand wrote:
> > Hello,
> > 
> > it seems the discussion on using -ffunction-sections for libgfortran
> > didn't really come to a conclusion:
> > http://gcc.gnu.org/ml/fortran/2009-03/msg00166.html
> > 
> > Is the above patch OK?  If not, I'd appreciate suggestions on how to
> > make it acceptable ...
> > 
> 
> I've reviewed the thread pointed to by the URL.  I think the
> patch would be okay provided the documentation of the options
> is updated because I had the same reaction as Tobias when I 
> read:

Sorry, I had already applied the patch after Tobias approved it
on Apr 16 ...    In any case:

>    Only use these options when there are significant benefits from
>    doing so.  When you specify these options, the assembler and
>    linker will create larger object and executable files and will
>    also be slower.  You will not be able to use `gprof' on all
>    systems if you specify this option and you may have problems with
>    debugging if you specify both this option and `-g'.
> 
> If the last sentence isn't true, then it needs to be amended.  If
> the last sentence is true and your patch breaks the abiblity to
> profile and debug code, then of course your patch is unacceptable.

This text has been unchanged since the feature was first added to GCC
in 1996.  Note that at that time, checks to prevent usage of the
feature in conjunction with either -g or a -p* option were added to
the compiler as well:

Mon Apr 15 03:43:11 1996  Jeffrey A. Law  <law@cygnus.com>

        * flags.h (flag_function_sections): Declare.
        * toplev.c (flag_function_sections): Define.
        (compile_file): Add warnings when -ffunction-sections is
        used with -g, or profiling.  Disable -ffunction-sections
        when profiling is used.  Add warning when -ffunction-sections
        is used on a target that doesn't support it.

As far as debugging is concerned, I have no idea what systems it might
have referred to at that time, but I do not think this applies to any
of the systems on which GCC is used today.  In fact, the check in
toplev.c that warned when using -ffunction-section in conjunction with
-g was removed last year.  See the discussion in:
http://gcc.gnu.org/bugzilla/show_bug.cgi?id=35597

Thus, I'd propose to remove the mention of -g from the docs as well.


As far as profiling is concerned, again I believe that on current
systems, there should be no conflict between -ffunction-sections
and profiling.  However, *this* check is still present in toplev.c
today and results in:

[uweigand@blc4eb184639574 ~]$ gcc -ffunction-sections -pg -c hello.c
hello.c:1: warning: -ffunction-sections disabled; it makes profiling impossible

While is probably no longer necessary on (most of?) today's systems,
I guess we should keep the documentation and implementation in sync.

In any case, this doesn't seem relevant to the libgfortran discussion
anyway, as the library is not built with -pg in the first place.
(The ability to profile some application that is simply linked with
a library built with -ffunction-sections should not be affected in
either case.)


Here's a patch to invoke.texi that rewords the rationale when to
use those options.  Any comments are appreciated ...

OK for mainline?

Bye,
Ulrich


ChangeLog:

	* doc/invoke.texi (-ffunction-sections / -fdata-sections): Reword
	rationale when to use these options.  Remove reference to problems
	with debugging on old systems.


Index: doc/invoke.texi
===================================================================
*** doc/invoke.texi	(revision 146647)
--- doc/invoke.texi	(working copy)
*************** function or the name of the data item de
*** 7184,7200 ****
  in the output file.
  
  Use these options on systems where the linker can perform optimizations
! to improve locality of reference in the instruction space.  Most systems
! using the ELF object format and SPARC processors running Solaris 2 have
! linkers with such optimizations.  AIX may have these optimizations in
! the future.
! 
! Only use these options when there are significant benefits from doing
! so.  When you specify these options, the assembler and linker will
! create larger object and executable files and will also be slower.
! You will not be able to use @code{gprof} on all systems if you
! specify this option and you may have problems with debugging if
! you specify both this option and @option{-g}.
  
  @item -fbranch-target-load-optimize
  @opindex fbranch-target-load-optimize
--- 7184,7201 ----
  in the output file.
  
  Use these options on systems where the linker can perform optimizations
! to improve locality of reference in the instruction space, or where the
! linker is able to discard unreferenced sections from its output.  Most
! systems using the ELF object format and SPARC processors running Solaris
! 2 have linkers with such optimizations.  AIX may have these optimizations
! in the future.
! 
! Only use these options on systems where there are benefits from doing so.
! When you specify these options, the assembler and linker will be slower
! and will create larger object and executable files.  On some systems,
! use of @option{-ffunction-sections} may interfere with profiling;
! GCC will automatically disable @option{-ffunction-sections} if the
! @option{-p} or @option{-pg} option is specified at the same time.
  
  @item -fbranch-target-load-optimize
  @opindex fbranch-target-load-optimize


-- 
  Dr. Ulrich Weigand
  GNU Toolchain for Linux on System z and Cell BE
  Ulrich.Weigand@de.ibm.com