Update template instantiation documentation

	* doc/extend.texi (Template Instantiation): Reorder options and
	de-emphasize -frepo.
	* doc/invoke.texi (C++ Dialect Options): Use -fstrict-enums in
	example instead of -frepo.

From-SVN: r228518

gcc/ChangeLog

+2015-10-06  Jonathan Wakely  <jwakely@redhat.com>
+
+	* doc/extend.texi (Template Instantiation): Reorder options and
+	de-emphasize -frepo.
+	* doc/invoke.texi (C++ Dialect Options): Use -fstrict-enums in
+	example instead of -frepo.
+
 2015-10-06  Eric Botcazou  <ebotcazou@adacore.com>
 
 	PR c/65345

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
@@ -19614,15 +19614,60 @@ of non-inline member templates into a separate file, which should be
 compiled separately.
 @end table
 
-When used with GNU ld version 2.8 or later on an ELF system such as
-GNU/Linux or Solaris 2, or on Microsoft Windows, G++ supports the
-Borland model.  On other systems, G++ implements neither automatic
-model.
+G++ implements the Borland model on targets where the linker supports it,
+including ELF targets (such as GNU/Linux), Mac OS X and Microsoft Windows.
+Otherwise G++ implements neither automatic model.
 
 You have the following options for dealing with template instantiations:
 
 @enumerate
 @item
+Do nothing.  Code written for the Borland model works fine, but
+each translation unit contains instances of each of the templates it
+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 of a template can be avoided by defining an explicit
+instantiation in one object file, and preventing the compiler from doing
+implicit instantiations in any other object files by using an explicit
+instantiation declaration, using the @code{extern template} syntax:
+
+@smallexample
+extern template int max (int, int);
+@end smallexample
+
+This syntax is defined in the C++ 2011 standard, but has been supported by
+G++ and other compilers since well before 2011.
+
+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.  You can scatter the explicit
+instantiations throughout your program, perhaps putting them in the
+translation units where the instances are used or the translation units
+that define the templates themselves; you can put all of the explicit
+instantiations you need into one big file; or you can create small files
+like
+
+@smallexample
+#include "Foo.h"
+#include "Foo.cc"
+
+template class Foo<int>;
+template ostream& operator <<
+                (ostream&, const Foo<int>&);
+@end smallexample
+
+@noindent
+for each of the instances you need, and create a template instantiation
+library from those.
+
+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.
+
+@item
 @opindex frepo
 Compile your template-using code with @option{-frepo}.  The compiler
 generates files with the extension @samp{.rpo} listing all of the
@@ -19633,8 +19678,8 @@ 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
-model, as it just works.  Code written for the Cfront model 
+This can be a suitable option for application code written for the Borland
+model, as it usually 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
 @code{#include <tmethods.cc>} to the end of each template header.
@@ -19653,25 +19698,8 @@ Compile your code with @option{-fno-implicit-templates} to disable the
 implicit generation of template instances, and explicitly instantiate
 all the ones you use.  This approach requires more knowledge of exactly
 which instances you need than do the others, but it's less
-mysterious and allows greater control.  You can scatter the explicit
-instantiations throughout your program, perhaps putting them in the
-translation units where the instances are used or the translation units
-that define the templates themselves; you can put all of the explicit
-instantiations you need into one big file; or you can create small files
-like
-
-@smallexample
-#include "Foo.h"
-#include "Foo.cc"
-
-template class Foo<int>;
-template ostream& operator <<
-                (ostream&, const Foo<int>&);
-@end smallexample
-
-@noindent
-for each of the instances you need, and create a template instantiation
-library from those.
+mysterious and allows greater control if you want to ensure that only
+the intended instances are used.
 
 If you are using Cfront-model code, you can probably get away with not
 using @option{-fno-implicit-templates} when compiling files that don't
@@ -19682,9 +19710,8 @@ compile it without @option{-fno-implicit-templates} so you get all of the
 instances required by your explicit instantiations (but not by any
 other files) without having to specify them as well.
 
-The ISO C++ 2011 standard allows forward declaration of explicit
-instantiations (with @code{extern}). G++ supports explicit instantiation
-declarations in C++98 mode and has extended the template instantiation
+In addition to forward declaration of explicit instantiations
+(with @code{extern}), G++ has extended the template instantiation
 syntax to support instantiation of the compiler support data for a
 template class (i.e.@: the vtable) without instantiating any of its
 members (with @code{inline}), and instantiation of only the static data
@@ -19692,17 +19719,9 @@ members of a template class, without the support data or member
 functions (with @code{static}):
 
 @smallexample
-extern template int max (int, int);
 inline template class Foo<int>;
 static template class Foo<int>;
 @end smallexample
-
-@item
-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.
 @end enumerate
 
 @node Bound member functions

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