1<html lang="en"> 2<head> 3<title>Template Instantiation - Using the GNU Compiler Collection (GCC)</title> 4<meta http-equiv="Content-Type" content="text/html"> 5<meta name="description" content="Using the GNU Compiler Collection (GCC)"> 6<meta name="generator" content="makeinfo 4.13"> 7<link title="Top" rel="start" href="index.html#Top"> 8<link rel="up" href="C_002b_002b-Extensions.html#C_002b_002b-Extensions" title="C++ Extensions"> 9<link rel="prev" href="C_002b_002b-Interface.html#C_002b_002b-Interface" title="C++ Interface"> 10<link rel="next" href="Bound-member-functions.html#Bound-member-functions" title="Bound member functions"> 11<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 12<!-- 13Copyright (C) 1988-2013 Free Software Foundation, Inc. 14 15Permission is granted to copy, distribute and/or modify this document 16under the terms of the GNU Free Documentation License, Version 1.3 or 17any later version published by the Free Software Foundation; with the 18Invariant Sections being ``Funding Free Software'', the Front-Cover 19Texts being (a) (see below), and with the Back-Cover Texts being (b) 20(see below). A copy of the license is included in the section entitled 21``GNU Free Documentation License''. 22 23(a) The FSF's Front-Cover Text is: 24 25 A GNU Manual 26 27(b) The FSF's Back-Cover Text is: 28 29 You have freedom to copy and modify this GNU Manual, like GNU 30 software. Copies published by the Free Software Foundation raise 31 funds for GNU development.--> 32<meta http-equiv="Content-Style-Type" content="text/css"> 33<style type="text/css"><!-- 34 pre.display { font-family:inherit } 35 pre.format { font-family:inherit } 36 pre.smalldisplay { font-family:inherit; font-size:smaller } 37 pre.smallformat { font-family:inherit; font-size:smaller } 38 pre.smallexample { font-size:smaller } 39 pre.smalllisp { font-size:smaller } 40 span.sc { font-variant:small-caps } 41 span.roman { font-family:serif; font-weight:normal; } 42 span.sansserif { font-family:sans-serif; font-weight:normal; } 43--></style> 44<link rel="stylesheet" type="text/css" href="../cs.css"> 45</head> 46<body> 47<div class="node"> 48<a name="Template-Instantiation"></a> 49<p> 50Next: <a rel="next" accesskey="n" href="Bound-member-functions.html#Bound-member-functions">Bound member functions</a>, 51Previous: <a rel="previous" accesskey="p" href="C_002b_002b-Interface.html#C_002b_002b-Interface">C++ Interface</a>, 52Up: <a rel="up" accesskey="u" href="C_002b_002b-Extensions.html#C_002b_002b-Extensions">C++ Extensions</a> 53<hr> 54</div> 55 56<h3 class="section">7.5 Where's the Template?</h3> 57 58<p><a name="index-template-instantiation-3524"></a> 59C++ templates are the first language feature to require more 60intelligence from the environment than one usually finds on a UNIX 61system. Somehow the compiler and linker have to make sure that each 62template instance occurs exactly once in the executable if it is needed, 63and not at all otherwise. There are two basic approaches to this 64problem, which are referred to as the Borland model and the Cfront model. 65 66 <dl> 67<dt>Borland model<dd>Borland C++ solved the template instantiation problem by adding the code 68equivalent of common blocks to their linker; the compiler emits template 69instances in each translation unit that uses them, and the linker 70collapses them together. The advantage of this model is that the linker 71only has to consider the object files themselves; there is no external 72complexity to worry about. This disadvantage is that compilation time 73is increased because the template code is being compiled repeatedly. 74Code written for this model tends to include definitions of all 75templates in the header file, since they must be seen to be 76instantiated. 77 78 <br><dt>Cfront model<dd>The AT&T C++ translator, Cfront, solved the template instantiation 79problem by creating the notion of a template repository, an 80automatically maintained place where template instances are stored. A 81more modern version of the repository works as follows: As individual 82object files are built, the compiler places any template definitions and 83instantiations encountered in the repository. At link time, the link 84wrapper adds in the objects in the repository and compiles any needed 85instances that were not previously emitted. The advantages of this 86model are more optimal compilation speed and the ability to use the 87system linker; to implement the Borland model a compiler vendor also 88needs to replace the linker. The disadvantages are vastly increased 89complexity, and thus potential for error; for some code this can be 90just as transparent, but in practice it can been very difficult to build 91multiple programs in one directory and one program in multiple 92directories. Code written for this model tends to separate definitions 93of non-inline member templates into a separate file, which should be 94compiled separately. 95</dl> 96 97 <p>When used with GNU ld version 2.8 or later on an ELF system such as 98GNU/Linux or Solaris 2, or on Microsoft Windows, G++ supports the 99Borland model. On other systems, G++ implements neither automatic 100model. 101 102 <p>You have the following options for dealing with template instantiations: 103 104 <ol type=1 start=1> 105<li><a name="index-frepo-3525"></a>Compile your template-using code with <samp><span class="option">-frepo</span></samp>. The compiler 106generates files with the extension ‘<samp><span class="samp">.rpo</span></samp>’ listing all of the 107template instantiations used in the corresponding object files that 108could be instantiated there; the link wrapper, ‘<samp><span class="samp">collect2</span></samp>’, 109then updates the ‘<samp><span class="samp">.rpo</span></samp>’ files to tell the compiler where to place 110those instantiations and rebuild any affected object files. The 111link-time overhead is negligible after the first pass, as the compiler 112continues to place the instantiations in the same files. 113 114 <p>This is your best option for application code written for the Borland 115model, as it just works. Code written for the Cfront model 116needs to be modified so that the template definitions are available at 117one or more points of instantiation; usually this is as simple as adding 118<code>#include <tmethods.cc></code> to the end of each template header. 119 120 <p>For library code, if you want the library to provide all of the template 121instantiations it needs, just try to link all of its object files 122together; the link will fail, but cause the instantiations to be 123generated as a side effect. Be warned, however, that this may cause 124conflicts if multiple libraries try to provide the same instantiations. 125For greater control, use explicit instantiation as described in the next 126option. 127 128 <li><a name="index-fno_002dimplicit_002dtemplates-3526"></a>Compile your code with <samp><span class="option">-fno-implicit-templates</span></samp> to disable the 129implicit generation of template instances, and explicitly instantiate 130all the ones you use. This approach requires more knowledge of exactly 131which instances you need than do the others, but it's less 132mysterious and allows greater control. You can scatter the explicit 133instantiations throughout your program, perhaps putting them in the 134translation units where the instances are used or the translation units 135that define the templates themselves; you can put all of the explicit 136instantiations you need into one big file; or you can create small files 137like 138 139 <pre class="smallexample"> #include "Foo.h" 140 #include "Foo.cc" 141 142 template class Foo<int>; 143 template ostream& operator << 144 (ostream&, const Foo<int>&); 145</pre> 146 <p class="noindent">for each of the instances you need, and create a template instantiation 147library from those. 148 149 <p>If you are using Cfront-model code, you can probably get away with not 150using <samp><span class="option">-fno-implicit-templates</span></samp> when compiling files that don't 151‘<samp><span class="samp">#include</span></samp>’ the member template definitions. 152 153 <p>If you use one big file to do the instantiations, you may want to 154compile it without <samp><span class="option">-fno-implicit-templates</span></samp> so you get all of the 155instances required by your explicit instantiations (but not by any 156other files) without having to specify them as well. 157 158 <p>The ISO C++ 2011 standard allows forward declaration of explicit 159instantiations (with <code>extern</code>). G++ supports explicit instantiation 160declarations in C++98 mode and has extended the template instantiation 161syntax to support instantiation of the compiler support data for a 162template class (i.e. the vtable) without instantiating any of its 163members (with <code>inline</code>), and instantiation of only the static data 164members of a template class, without the support data or member 165functions (with (<code>static</code>): 166 167 <pre class="smallexample"> extern template int max (int, int); 168 inline template class Foo<int>; 169 static template class Foo<int>; 170</pre> 171 <li>Do nothing. Pretend G++ does implement automatic instantiation 172management. Code written for the Borland model works fine, but 173each translation unit contains instances of each of the templates it 174uses. In a large program, this can lead to an unacceptable amount of code 175duplication. 176 </ol> 177 178 </body></html> 179 180