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?
commit b115ee74b5aa8cf7e191456b609fa14bb6890e3d
Author: Jonathan Wakely <jwak...@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@.
 

Reply via email to