diff mbox

Update template instantiation documentation

Message ID 20151003124714.GE12094@redhat.com
State New
Headers show

Commit Message

Jonathan Wakely Oct. 3, 2015, 12:47 p.m. UTC 
https://gcc.gnu.org/onlinedocs/gcc/Template-Instantiation.html
currently says that using -frepo "is your best option for application
code written for the Borland model, as it just works."

That was true at one point, but as can be seen from the mentions of
binutils 2.8 and Solaris 2, the information there is pretty old.

Since then -frepo has bitrotted occasionally, and it's much simpler to
rely on implicit instantiations in COMDAT sections, controlling
specific instantiations with explicit instantiations if needed (using
'extern template' which was standardised in C++11).

See https://gcc.gnu.org/bugzilla/show_bug.cgi?id=51910#c2 for an
example of bitrot (now fixed) and people being persuaded by the docs
that -frepo is the best option.

So this revises the docs, to downplay the usefulness of -frepo,
and to endorse the "do nothing" model (with selective explicit
instantations as needed).

It also changes another mention of -frepo to use a different C++-only
option, to further de-emphasize -frepo.

OK for trunk?

Comments

Sandra Loosemore Oct. 3, 2015, 4:44 p.m. UTC | #1 
On 10/03/2015 06:47 AM, Jonathan Wakely wrote:
> https://gcc.gnu.org/onlinedocs/gcc/Template-Instantiation.html
> currently says that using -frepo "is your best option for application
> code written for the Borland model, as it just works."
>
> That was true at one point, but as can be seen from the mentions of
> binutils 2.8 and Solaris 2, the information there is pretty old.
>
> Since then -frepo has bitrotted occasionally, and it's much simpler to
> rely on implicit instantiations in COMDAT sections, controlling
> specific instantiations with explicit instantiations if needed (using
> 'extern template' which was standardised in C++11).
>
> See https://gcc.gnu.org/bugzilla/show_bug.cgi?id=51910#c2 for an
> example of bitrot (now fixed) and people being persuaded by the docs
> that -frepo is the best option.
>
> So this revises the docs, to downplay the usefulness of -frepo,
> and to endorse the "do nothing" model (with selective explicit
> instantations as needed).
>
> It also changes another mention of -frepo to use a different C++-only
> option, to further de-emphasize -frepo.
>
> OK for trunk?

Thanks for tackling this.  I remember thinking that this section looked 
bit-rotted when I was reviewing the manual earlier this year.  Your 
patch looks like a step in the right direction, but can I get you to fix 
a couple other things while you're at it?

First, I think the reference to ancient ld versions is confusing, and it 
would be better to rewrite that to emphasize that this is the default 
behavior on most targets.  (I'd guess that anybody trying to use a 
recent GCC release with an ld version from 1996 is going to run into 
more critical blocking issues than this one.)  Maybe something like:

"G++ implements the Borland model on targets where the linker supports 
it, including both ELF targets (such as GNU/Linux) and Microsoft 
Windows.  Otherwise G++ implements neither automatic model."

Second, if "Do nothing" is now the recommended way to handle this, let's 
move that option to the front of the itemized list instead of the end. 
Also, I'm confused by the "pretend" here; can we just delete that sentence?

-Sandra
Andrew Pinski Oct. 3, 2015, 4:49 p.m. UTC | #2 
On Sat, Oct 3, 2015 at 9:44 AM, Sandra Loosemore
<sandra@codesourcery.com> wrote:
> On 10/03/2015 06:47 AM, Jonathan Wakely wrote:
>>
>> https://gcc.gnu.org/onlinedocs/gcc/Template-Instantiation.html
>> currently says that using -frepo "is your best option for application
>> code written for the Borland model, as it just works."
>>
>> That was true at one point, but as can be seen from the mentions of
>> binutils 2.8 and Solaris 2, the information there is pretty old.
>>
>> Since then -frepo has bitrotted occasionally, and it's much simpler to
>> rely on implicit instantiations in COMDAT sections, controlling
>> specific instantiations with explicit instantiations if needed (using
>> 'extern template' which was standardised in C++11).
>>
>> See https://gcc.gnu.org/bugzilla/show_bug.cgi?id=51910#c2 for an
>> example of bitrot (now fixed) and people being persuaded by the docs
>> that -frepo is the best option.
>>
>> So this revises the docs, to downplay the usefulness of -frepo,
>> and to endorse the "do nothing" model (with selective explicit
>> instantations as needed).
>>
>> It also changes another mention of -frepo to use a different C++-only
>> option, to further de-emphasize -frepo.
>>
>> OK for trunk?
>
>
> Thanks for tackling this.  I remember thinking that this section looked
> bit-rotted when I was reviewing the manual earlier this year.  Your patch
> looks like a step in the right direction, but can I get you to fix a couple
> other things while you're at it?
>
> First, I think the reference to ancient ld versions is confusing, and it
> would be better to rewrite that to emphasize that this is the default
> behavior on most targets.  (I'd guess that anybody trying to use a recent
> GCC release with an ld version from 1996 is going to run into more critical
> blocking issues than this one.)  Maybe something like:
>
> "G++ implements the Borland model on targets where the linker supports it,
> including both ELF targets (such as GNU/Linux) and Microsoft Windows.
> Otherwise G++ implements neither automatic model."


Add "And Mac OS X" to that too.  So people don't use that against us
for the reason why Apple went to clang/LLVM.

Thanks,
Andrew

>
> Second, if "Do nothing" is now the recommended way to handle this, let's
> move that option to the front of the itemized list instead of the end. Also,
> I'm confused by the "pretend" here; can we just delete that sentence?
>
> -Sandra
>
Jonathan Wakely Oct. 3, 2015, 5:44 p.m. UTC | #3 
On 03/10/15 09:49 -0700, Andrew Pinski wrote:
>Add "And Mac OS X" to that too.  So people don't use that against us
>for the reason why Apple went to clang/LLVM.

Will do.
Jonathan Wakely Oct. 3, 2015, 5:45 p.m. UTC | #4 
On 03/10/15 10:44 -0600, Sandra Loosemore wrote:
>Thanks for tackling this.  I remember thinking that this section 
>looked bit-rotted when I was reviewing the manual earlier this year.  
>Your patch looks like a step in the right direction, but can I get you 
>to fix a couple other things while you're at it?
>
>First, I think the reference to ancient ld versions is confusing, and 
>it would be better to rewrite that to emphasize that this is the 
>default behavior on most targets.  (I'd guess that anybody trying to 
>use a recent GCC release with an ld version from 1996 is going to run 
>into more critical blocking issues than this one.)  Maybe something 
>like:
>
>"G++ implements the Borland model on targets where the linker supports 
>it, including both ELF targets (such as GNU/Linux) and Microsoft 
>Windows.  Otherwise G++ implements neither automatic model."
>
>Second, if "Do nothing" is now the recommended way to handle this, 
>let's move that option to the front of the itemized list instead of 
>the end. Also, I'm confused by the "pretend" here; can we just delete 
>that sentence?

Yes, all good ideas, I'll incorporate these asap.
diff mbox

Patch

commit b115ee74b5aa8cf7e191456b609fa14bb6890e3d
Author: Jonathan Wakely <jwakely@redhat.com>
Date:   Mon Sep 1 15:50:24 2014 +0100

    Update template instantiation documentation
    
    	* doc/extend.texi (Template Instantiation): Stop implying -frepo is
    	the best option.
    	* doc/invoke.texi (C++ Dialect Options): Use -fstrict-enums in
    	example instead of -frepo.

diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index 8406945..6c19682 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -19574,8 +19574,8 @@  If any calls are not inlined, you will get linker errors.
 @section Where's the Template?
 @cindex template instantiation
 
-C++ templates are the first language feature to require more
-intelligence from the environment than one usually finds on a UNIX
+C++ templates were the first language feature to require more
+intelligence from the environment than was traditionally found on a UNIX
 system.  Somehow the compiler and linker have to make sure that each
 template instance occurs exactly once in the executable if it is needed,
 and not at all otherwise.  There are two basic approaches to this
@@ -19588,7 +19588,7 @@  equivalent of common blocks to their linker; the compiler emits template
 instances in each translation unit that uses them, and the linker
 collapses them together.  The advantage of this model is that the linker
 only has to consider the object files themselves; there is no external
-complexity to worry about.  This disadvantage is that compilation time
+complexity to worry about.  The disadvantage is that compilation time
 is increased because the template code is being compiled repeatedly.
 Code written for this model tends to include definitions of all
 templates in the header file, since they must be seen to be
@@ -19633,7 +19633,7 @@  those instantiations and rebuild any affected object files.  The
 link-time overhead is negligible after the first pass, as the compiler
 continues to place the instantiations in the same files.
 
-This is your best option for application code written for the Borland
+This can be a suitable option for application code written for the Borland
 model, as it just works.  Code written for the Cfront model 
 needs to be modified so that the template definitions are available at
 one or more points of instantiation; usually this is as simple as adding
@@ -19701,8 +19701,21 @@  static template class Foo<int>;
 Do nothing.  Pretend G++ does implement automatic instantiation
 management.  Code written for the Borland model works fine, but
 each translation unit contains instances of each of the templates it
-uses.  In a large program, this can lead to an unacceptable amount of code
-duplication.
+uses.  The duplicate instances will be discarded by the linker, but in
+a large program, this can lead to an unacceptable amount of code
+duplication in object files or shared libraries.
+
+Duplicate instances can be avoided by selective use of explicit
+instantiation declarations (using the @code{extern template} syntax
+described above) and explicit instantiation definitions for individual
+instances. Explicit instantiations can be used for the largest or most
+frequently duplicated instances, without having to know exactly which
+other instances are used in the rest of the program.
+
+This is the simplest option, but also offers flexibility and
+fine-grained control when necessary. It is also the most portable
+alternative and programs using this approach will work with most modern
+compilers.
 @end enumerate
 
 @node Bound member functions
diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index 3a9594c..8819c02 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -2085,11 +2085,11 @@  regardless of what language your program is in.  For example, you
 might compile a file @file{firstClass.C} like this:
 
 @smallexample
-g++ -g -frepo -O -c firstClass.C
+g++ -g -fstrict-enums -O -c firstClass.C
 @end smallexample
 
 @noindent
-In this example, only @option{-frepo} is an option meant
+In this example, only @option{-fstrict-enums} is an option meant
 only for C++ programs; you can use the other options with any
 language supported by GCC@.