1. One would like to end up with only one copy of each instantiated entity across all the object files that make up a program. (This of course applies to entities with external linkage.)
   
   The language allows one to write a specialization of a template entity, i.e., a specific version to be used in place of a version generated from the template for a specific data type. (One could, for example, write a version of Stack<int>, or of just Stack<int>::push, that replaces the template-generated version; often, such a specialization provides a more efficient representation for a particular data type.) Since the compiler cannot know, when compiling a reference to a template entity, if a specialization for that entity will be provided in another compilation, it cannot do the instantiation automatically in any source file that references it. (The modern C++ language requires that a specialization be declared in every compilation in which it is used, but for compatibility with existing code and older compilers the Comeau front end does not require that in some modes. See the command-line option --no_distinct_template_signatures.)
   
   
2. The language also dictates that template functions that are not referenced should not be compiled, that, in fact, such functions might contain semantic errors that would prevent them from being compiled. Therefore, a reference to a template class should not automatically instantiate all the member functions of that class.
   
   

The Comeau C++ front end provides an instantiation mechanism that does automatic instantiation at link time (on most platforms). For cases where the programmer wants more explicit control over instantiation, the front end also provides instantiation modes and instantiation pragmas, which can be used to exert fine-grained control over the instantiation process.

The goal of an automatic instantiation mode is to provide painless instantiation. The programmer should be able to compile source files to object code, then link them and run the resulting program, and never have to worry about how the necessary instantiations get done.

In practice, this is hard for a compiler to do, and different compilers use different automatic instantiation schemes with different strengths and weaknesses:

1. AT&T/USL/Novell's cfront (which Comeau C++ 3.0 is based on) product saves information about each file it compiles in a special directory called ptrepository. It instantiates nothing during normal compilations. At link time, it looks for entities that are referenced but not defined, and whose mangled names indicate that they are template entities. For each such entity, it consults the ptrepository information to find the file containing the source for the entity, and it does a compilation of the source to generate an object file containing object code for that entity. This object code for instantiated objects is then combined with the "normal" object code in the link step.
   
   The programmer using cfront must follow a particular coding convention: all templates must be declared in ".h" files, and for each such file there must be a corresponding ".C" file containing the associated source definitions. The compiler is never told about the ".C" files explicitly; one does not, for example, compile them in the normal way. The link step looks for them when and if it needs them, and does so by taking the ".h" file name and replacing its suffix.
   
   

   This scheme has the disadvantage that it does a separate compilation for each instantiated function (or, at best, one compilation for all the member functions of one class). Even though the function itself is often quite small, it must be compiled along with the declarations for the types on which the instantiation is based, and those declarations can easily run into many thousands of lines. For large systems, these compilations can take a very long time. The link step tries to be smart about recompiling instantiations only when necessary, but because it keeps no fine- grained dependency information, it is often forced to "recompile the world" for a minor change in a ".h" file. In addition, cfront has no way of ensuring that preprocessing symbols are set correctly when it does these instantiation compilations, if preprocessing symbols are set other than on the command line.
   
   

2. Borland's C++ compiler instantiates everything referenced in a compilation, then uses a special linker to remove duplicate definitions of instantiated functions.
   
   The programmer using Borland's compiler must make sure that every compilation sees all the source code it needs to instantiate all the template entities referenced in that compilation. That is, one cannot refer to a template entity in a source file if a definition for that entity is not included by that source file. In practice, this means that either all the definition code is put directly in the ".h" files, or that each ".h" file includes an associated ".C" (actually, ".CPP") file.
   
   

   This scheme is straightforward, and works well for small programs. For large systems, however, it tends to produce very large object files, because each object file must contain object code (and symbolic debugging information) for each template entity it references.
   
   

1. The Borland convention: each ".h" file that declares a template entity also contains either the definition of the entity or includes another file containing the definition.
   
   
2. Implicit inclusion: when the compiler sees a template declaration in a ".h" file and discovers a need to instantiate that entity, it is given permission to go off looking for an associated definition file having the same base name and a different suffix, and it implicitly includes that file at the end of the compilation. This method allows most programs written using the cfront convention to be compiled with Comeau's approach. See the section on implicit inclusion.
   
   
3. The ad hoc approach: the programmer makes sure that the files that define template entities also have the definitions of all the available types, and adds code or pragmas in those files to request instantiation of the entities there.
   
   

1. The first time the source files of a program are compiled, no template entities are instantiated. However, the generated object files contain information about things that could have been instantiated in each compilation. For any source file that makes use of a template instantiation an associated ".ii" file is created if one does not already exist (e.g., the compilation of abc.C would result in the creation of abc.ii).
   
   
2. When the object files are linked together, a program called the prelinker is run. It examines the object files, looking for references and definitions of template entities, and for the added information about entities that could be instantiated.
   
   
3. If the prelinker finds a reference to a template entity for which there is no definition anywhere in the set of object files, it looks for a file that indicates that it could instantiate that template entity. When it finds such a file, it assigns the instantiation to it. The set of instantiations assigned to a given file is recorded in the associated ".ii" file.
   
   
4. The prelinker then executes the compiler again to recompile each file for which the ".ii" file was changed.
   
   
5. When the compiler compiles a file, it reads the ".ii" file for that file and obeys the instantiation requests therein. It produces a new object file containing the requested template entities (and all the other things that were already in the object file).
   
   
6. The prelinker repeats steps 3--5 until there are no more instantiations to be adjusted.
   
   
7. The object files are linked together.
   
   

Normally, when a file is compiled, no template entities are instantiated (except those assigned to the file by automatic instantiation). The overall instantiation mode can, however, be changed by a command line option:

• -tnone Do not automatically create instantiations of any template entities. This is the default. It is also the usually appropriate mode when automatic instantiation is done.
  
  
• -tused Instantiate those template entities that were used in the compilation. This will include all static data members for which there are template definitions.
  
  
• -tall Instantiate all template entities declared or referenced in the compilation unit. For each fully instantiated template class, all of its member functions and static data members will be instantiated whether or not they were used. Nonmember template functions will be instantiated even if the only reference was a declaration.
  
  
• -tlocal Similar to -tused except that the functions are given internal linkage. This is intended to provide a very simple mechanism for those getting started with templates. The compiler will instantiate the functions that are used in each compilation unit as local functions, and the program will link and run correctly (barring problems due to multiple copies of local static variables.) However, one may end up with many copies of the instantiated functions, so this is not suitable for production use. -tlocal can not be used in conjunction with automatic template instantiation. If automatic instantiation is enabled by default, it will be disabled by the -tlocal option. If automatic instantiation is not enabled by default, use of -tlocal and -T is an error.
  
  

Instantiation pragmas can be used to control the instantiation of specific template entities or sets of template entities. There are three instantiation pragmas:

1. The instantiate pragma causes a specified entity to be instantiated.
   
   
2. The do_not_instantiate pragma suppresses the instantiation of a specified entity. It is typically used to suppress the instantiation of an entity for which a specific definition will be supplied.
   
   
3. The can_instantiate pragma indicates that a specified entity can be instantiated in the current compilation, but need not be; it is used in conjunction with automatic instantiation, to indicate potential sites for instantiation if the template entity turns out to be required.
   
   

• a template class name A<int>
  
  
• a template class declaration class A<int>
  
  
• a member function name A<int>::f
  
  
• a static data member name A<int>::i
  
  
• a static data declaration int A<int>::i
  
  
• a member function declaration void A<int>::f(int, char)
  
  
• a template function declaration char* f(int, float)
  
  

template <class T> void f1(T);  // No body provided
template <class T> void g1(T);  // No body provided
void f1(int) {}  // Specific definition
int main()
{
   int     i;
   double  d;
   f1(i);
   f1(d);
   g1(i);
   g1(d);
   return 0;
}
#pragma instantiate void f1(int) // error - specific def.
#pragma instantiate void g1(int)  // error - no body provided