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@.