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