| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <html> |
| <!-- Copyright (C) 1988-2015 Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.3 or |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being "Funding Free Software", the Front-Cover |
| Texts being (a) (see below), and with the Back-Cover Texts being (b) |
| (see below). A copy of the license is included in the section entitled |
| "GNU Free Documentation License". |
| |
| (a) The FSF's Front-Cover Text is: |
| |
| A GNU Manual |
| |
| (b) The FSF's Back-Cover Text is: |
| |
| You have freedom to copy and modify this GNU Manual, like GNU |
| software. Copies published by the Free Software Foundation raise |
| funds for GNU development. --> |
| <!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ --> |
| <head> |
| <title>Using the GNU Compiler Collection (GCC): Template Instantiation</title> |
| |
| <meta name="description" content="Using the GNU Compiler Collection (GCC): Template Instantiation"> |
| <meta name="keywords" content="Using the GNU Compiler Collection (GCC): Template Instantiation"> |
| <meta name="resource-type" content="document"> |
| <meta name="distribution" content="global"> |
| <meta name="Generator" content="makeinfo"> |
| <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> |
| <link href="index.html#Top" rel="start" title="Top"> |
| <link href="Option-Index.html#Option-Index" rel="index" title="Option Index"> |
| <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> |
| <link href="C_002b_002b-Extensions.html#C_002b_002b-Extensions" rel="up" title="C++ Extensions"> |
| <link href="Bound-member-functions.html#Bound-member-functions" rel="next" title="Bound member functions"> |
| <link href="C_002b_002b-Interface.html#C_002b_002b-Interface" rel="prev" title="C++ Interface"> |
| <style type="text/css"> |
| <!-- |
| a.summary-letter {text-decoration: none} |
| blockquote.smallquotation {font-size: smaller} |
| div.display {margin-left: 3.2em} |
| div.example {margin-left: 3.2em} |
| div.indentedblock {margin-left: 3.2em} |
| div.lisp {margin-left: 3.2em} |
| div.smalldisplay {margin-left: 3.2em} |
| div.smallexample {margin-left: 3.2em} |
| div.smallindentedblock {margin-left: 3.2em; font-size: smaller} |
| div.smalllisp {margin-left: 3.2em} |
| kbd {font-style:oblique} |
| pre.display {font-family: inherit} |
| pre.format {font-family: inherit} |
| pre.menu-comment {font-family: serif} |
| pre.menu-preformatted {font-family: serif} |
| pre.smalldisplay {font-family: inherit; font-size: smaller} |
| pre.smallexample {font-size: smaller} |
| pre.smallformat {font-family: inherit; font-size: smaller} |
| pre.smalllisp {font-size: smaller} |
| span.nocodebreak {white-space:nowrap} |
| span.nolinebreak {white-space:nowrap} |
| span.roman {font-family:serif; font-weight:normal} |
| span.sansserif {font-family:sans-serif; font-weight:normal} |
| ul.no-bullet {list-style: none} |
| --> |
| </style> |
| |
| |
| </head> |
| |
| <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> |
| <a name="Template-Instantiation"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="Bound-member-functions.html#Bound-member-functions" accesskey="n" rel="next">Bound member functions</a>, Previous: <a href="C_002b_002b-Interface.html#C_002b_002b-Interface" accesskey="p" rel="prev">C++ Interface</a>, Up: <a href="C_002b_002b-Extensions.html#C_002b_002b-Extensions" accesskey="u" rel="up">C++ Extensions</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html#Option-Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <hr> |
| <a name="Where_0027s-the-Template_003f"></a> |
| <h3 class="section">7.5 Where’s the Template?</h3> |
| <a name="index-template-instantiation"></a> |
| |
| <p>C++ templates are the first language feature to require more |
| intelligence from the environment than one usually finds 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 |
| problem, which are referred to as the Borland model and the Cfront model. |
| </p> |
| <dl compact="compact"> |
| <dt>Borland model</dt> |
| <dd><p>Borland C++ solved the template instantiation problem by adding the code |
| 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 |
| 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 |
| instantiated. |
| </p> |
| </dd> |
| <dt>Cfront model</dt> |
| <dd><p>The AT&T C++ translator, Cfront, solved the template instantiation |
| problem by creating the notion of a template repository, an |
| automatically maintained place where template instances are stored. A |
| more modern version of the repository works as follows: As individual |
| object files are built, the compiler places any template definitions and |
| instantiations encountered in the repository. At link time, the link |
| wrapper adds in the objects in the repository and compiles any needed |
| instances that were not previously emitted. The advantages of this |
| model are more optimal compilation speed and the ability to use the |
| system linker; to implement the Borland model a compiler vendor also |
| needs to replace the linker. The disadvantages are vastly increased |
| complexity, and thus potential for error; for some code this can be |
| just as transparent, but in practice it can been very difficult to build |
| multiple programs in one directory and one program in multiple |
| directories. Code written for this model tends to separate definitions |
| of non-inline member templates into a separate file, which should be |
| compiled separately. |
| </p></dd> |
| </dl> |
| |
| <p>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. |
| </p> |
| <p>You have the following options for dealing with template instantiations: |
| </p> |
| <ol> |
| <li> <a name="index-frepo-1"></a> |
| Compile your template-using code with <samp>-frepo</samp>. The compiler |
| generates files with the extension ‘<samp>.rpo</samp>’ listing all of the |
| template instantiations used in the corresponding object files that |
| could be instantiated there; the link wrapper, ‘<samp>collect2</samp>’, |
| then updates the ‘<samp>.rpo</samp>’ files to tell the compiler where to place |
| 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. |
| |
| <p>This is your best 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 |
| <code>#include <tmethods.cc></code> to the end of each template header. |
| </p> |
| <p>For library code, if you want the library to provide all of the template |
| instantiations it needs, just try to link all of its object files |
| together; the link will fail, but cause the instantiations to be |
| generated as a side effect. Be warned, however, that this may cause |
| conflicts if multiple libraries try to provide the same instantiations. |
| For greater control, use explicit instantiation as described in the next |
| option. |
| </p> |
| </li><li> <a name="index-fno_002dimplicit_002dtemplates-1"></a> |
| Compile your code with <samp>-fno-implicit-templates</samp> 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 |
| |
| <div class="smallexample"> |
| <pre class="smallexample">#include "Foo.h" |
| #include "Foo.cc" |
| |
| template class Foo<int>; |
| template ostream& operator << |
| (ostream&, const Foo<int>&); |
| </pre></div> |
| |
| <p>for each of the instances you need, and create a template instantiation |
| library from those. |
| </p> |
| <p>If you are using Cfront-model code, you can probably get away with not |
| using <samp>-fno-implicit-templates</samp> when compiling files that don’t |
| ‘<samp>#include</samp>’ the member template definitions. |
| </p> |
| <p>If you use one big file to do the instantiations, you may want to |
| compile it without <samp>-fno-implicit-templates</samp> 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. |
| </p> |
| <p>The ISO C++ 2011 standard allows forward declaration of explicit |
| instantiations (with <code>extern</code>). G++ supports explicit instantiation |
| declarations in C++98 mode and 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</code>), and instantiation of only the static data |
| members of a template class, without the support data or member |
| functions (with (<code>static</code>): |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">extern template int max (int, int); |
| inline template class Foo<int>; |
| static template class Foo<int>; |
| </pre></div> |
| |
| </li><li> 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. |
| </li></ol> |
| |
| <hr> |
| <div class="header"> |
| <p> |
| Next: <a href="Bound-member-functions.html#Bound-member-functions" accesskey="n" rel="next">Bound member functions</a>, Previous: <a href="C_002b_002b-Interface.html#C_002b_002b-Interface" accesskey="p" rel="prev">C++ Interface</a>, Up: <a href="C_002b_002b-Extensions.html#C_002b_002b-Extensions" accesskey="u" rel="up">C++ Extensions</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html#Option-Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| |
| |
| |
| </body> |
| </html> |