visus
/
toolchain-gcc-arm-embedded

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Copyright (C) 1988-2020 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 6.5, http://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Template Instantiation (Using the GNU Compiler Collection (GCC))</title>

<meta name="description" content="Template Instantiation (Using the GNU Compiler Collection (GCC))">
<meta name="keywords" content="Template Instantiation (Using the GNU Compiler Collection (GCC))">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<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.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
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.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en">
<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> &nbsp; [<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&rsquo;s the Template?</h3>
<a name="index-template-instantiation"></a>

<p>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
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.  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
instantiated.
</p>
</dd>
<dt>Cfront model</dt>
<dd><p>The AT&amp;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>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.
</p>
<p>You have the following options for dealing with template instantiations:
</p>
<ol>
<li> 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.

<p>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</code> syntax:
</p>
<div class="smallexample">
<pre class="smallexample">extern template int max (int, int);
</pre></div>

<p>This syntax is defined in the C++ 2011 standard, but has been supported by
G++ and other compilers since well before 2011.
</p>
<p>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
</p>
<div class="smallexample">
<pre class="smallexample">#include &quot;Foo.h&quot;
#include &quot;Foo.cc&quot;

template class Foo&lt;int&gt;;
template ostream&amp; operator &lt;&lt;
                (ostream&amp;, const Foo&lt;int&gt;&amp;);
</pre></div>

<p>for each of the instances you need, and create a template instantiation
library from those.
</p>
<p>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.
</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&rsquo;s less
mysterious and allows greater control if you want to ensure that only
the intended instances are used.

<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&rsquo;t
&lsquo;<samp>#include</samp>&rsquo; 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>In addition to forward declaration of explicit instantiations
(with <code>extern</code>), 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</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">inline template class Foo&lt;int&gt;;
static template class Foo&lt;int&gt;;
</pre></div>
</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> &nbsp; [<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>