By MainID


2009-01-30 10:06:50 8 Comments

Quote from The C++ standard library: a tutorial and handbook:

The only portable way of using templates at the moment is to implement them in header files by using inline functions.

Why is this?

(Clarification: header files are not the only portable solution. But they are the most convenient portable solution.)

16 comments

@Luc Touraille 2009-01-30 10:26:41

It is not necessary to put the implementation in the header file, see the alternative solution at the end of this answer.

Anyway, the reason your code is failing is that, when instantiating a template, the compiler creates a new class with the given template argument. For example:

template<typename T>
struct Foo
{
    T bar;
    void doSomething(T param) {/* do stuff using T */}
};

// somewhere in a .cpp
Foo<int> f; 

When reading this line, the compiler will create a new class (let's call it FooInt), which is equivalent to the following:

struct FooInt
{
    int bar;
    void doSomething(int param) {/* do stuff using int */}
}

Consequently, the compiler needs to have access to the implementation of the methods, to instantiate them with the template argument (in this case int). If these implementations were not in the header, they wouldn't be accessible, and therefore the compiler wouldn't be able to instantiate the template.

A common solution to this is to write the template declaration in a header file, then implement the class in an implementation file (for example .tpp), and include this implementation file at the end of the header.

// Foo.h
template <typename T>
struct Foo
{
    void doSomething(T param);
};

#include "Foo.tpp"

// Foo.tpp
template <typename T>
void Foo<T>::doSomething(T param)
{
    //implementation
}

This way, implementation is still separated from declaration, but is accessible to the compiler.

Alternative solution

Another solution is to keep the implementation separated, and explicitly instantiate all the template instances you'll need:

// Foo.h

// no implementation
template <typename T> struct Foo { ... };

//----------------------------------------    
// Foo.cpp

// implementation of Foo's methods

// explicit instantiations
template class Foo<int>;
template class Foo<float>;
// You will only be able to use Foo with int or float

If my explanation isn't clear enough, you can have a look at the C++ Super-FAQ on this subject.

@Mankarse 2011-05-28 10:21:43

Actually the explicit instantiation needs to be in a .cpp file which has access to the definitions for all of Foo's member functions, rather than in the header.

@xcrypt 2012-01-14 23:56:10

"the compiler needs to have access to the implementation of the methods, to instantiate them with the template argument (in this case int). If these implementations were not in the header, they wouldn't be accessible" But why is an implementation in the .cpp file not accessible to the compiler? A compiler can also access .cpp information, how else would it turn them into .obj files? EDIT: answer to this question is in the link provided in this answer...

@zinking 2012-08-23 09:47:07

I don't think this explains the question that clearly, the key thing is obviously related with the compilation UNIT which is not mentioned in this post

@Gabson 2014-02-21 13:55:18

is 'struct' means the same than 'class' here ?

@Luc Touraille 2014-02-21 14:12:19

@Gabson: structs and classes are equivalent with the exception that the default access modifier for classes is "private", while it is public for structs. There are some other tiny differences that you can learn by looking at this question.

@vonbrand 2014-03-10 02:49:33

@xcrypt, when compiling some other .cpp file, the .cpp with the implementation is unknown (and might even not be available, think library).

@Luc Touraille 2014-05-13 16:10:12

@Deduplicator: No, the members of a class are private by default, not protected.

@Aaron McDaid 2015-08-05 09:39:47

I've added a sentence at the very start of this answer to clarify that the question is based on a false premise. If somebody asks "Why is X true?" when in fact X is not true, we should quickly reject that assumption.

@mrgloom 2015-12-07 14:13:12

Can we use explicit instantiations with template function without a class?

@Luc Touraille 2015-12-07 15:58:05

@mrgloom: Yes, a function template can be explicitely instantiated juste like a class template (see How do I explicitely instantiate a template function).

@Edward Karak 2016-02-21 14:55:43

Using the template instant generates error C2512 "no appropriate default constructor available", even though i defined the default constructor as foo() { }

@FaceBro 2016-03-09 10:01:20

One can never understand this without knowing "separate compilation model", which is described in the link..

@sunny moon 2016-08-12 16:33:54

Would like to add that Visual Studio (2015 Community Up3 in my case) might misbehave wildly when trying to implement the first solution (i.e. #including at the bottom) - see this for example. Had to exclude and re-include the implementation file from/to project to make it compile - rather ridiculous..

@gromit190 2017-03-08 18:43:34

I'd like to know, is it possible to do the explicit instantiations from somewhere other than the class' header or source file? For instance, do them in main.cpp?

@Luc Touraille 2017-03-09 14:57:30

@Birger To instantiate a template, you need its definition. If the definition is not in the header file, the only place you can do instantiations is in the implementation file that contains the definition. If the definition is in the header file, anyone with access to the header file can instantiate the template, either by using it directly (by defining a variable of the type template, or calling the function template for instance) or by making an explicit instantiation (instantiating the template without using it).

@FaceBro 2017-06-08 09:19:41

Explicit instantiation still needs the definition of the template. In this sense, it's not the second way, there is only one way .

@Ahmed 2017-07-08 15:30:58

I created a template library .cpp and .h , and only included the header . Was trying to know why I am getting linker error for hours and finally with this answer I understand why

@Luc Touraille 2017-11-17 08:41:26

@Andreyua Do you mean the example with explicit instantiations? I don't really see what additional information I could give, you just need to write in a .cpp the lines that instantiate your template with the arguments you want.

@Adam 2018-01-21 17:07:18

"Consequently, the compiler needs to have access to the implementation of the methods". Why would the compiler need to instantiate the methods? It does not when I'm declaring a non-template function, which is implemented in another cpp. Then, I think, it's the linker's job to find the implementation according to the function signature or how it does it. I don't see why the linker wouldn't just grab the instantiated signature and in addition to finding a normal function implementation, in case of a template signature it would find a template definition to generate the code.

@Adam 2018-01-21 17:12:50

Aha, it's not what linkers do, generating code, right? Then I think the thought process above should be in the answer. Because normally (when not using templates), compiler does not need to have access to the implementation. And that's maybe the why that people want to know.

@Lightness Races with Monica 2018-02-22 00:49:56

@Adam: I agree - that wording in this answer is not quite right. But I think Luc was trying to simplify (and used "compiler" in place of "your compiler and linker").

@donlan 2018-03-08 14:46:56

Is this why builds slow down dramatically after adding header libraries?

@Swift - Friday Pie 2018-09-10 09:10:28

I think, answer needs an update.it's no longer "only in header", it's implementation-dependent, according to ISO standard's description of translation process. Compilers allowed to store data about template instantiation and use it on link stage. But that means that templates might be defined in .cpp files but it's up to compiler to support that.

@anddero 2018-10-27 10:43:45

Emphasis on using a file extensions like .tpp in the second case (it must not be .cpp, otherwise there will be problems, or the use of macros is required to prevent cyclical inclusions).

@Rick 2018-10-30 13:59:42

@LightnessRacesinOrbit Hi, Big Boss. I would like to ask: since the answer indicates a way which is to do some explicit instantiations in .cpp file. So I think in all the other files that use any instantiations of that template, I should/must write extern template *delaration* for saving costs, am I right? Otherwise there's no meaning of using explicit instantiations.

@Lightness Races with Monica 2018-10-30 15:40:11

@Rick: I guess you can do. I don't believe it's necessary.

@M.kazem Akhgary 2019-09-28 07:06:07

Thanks for the answer. I get it but that's an stupid limitation! like it's not rocket science, they could just make it possible. I think I will go with explicit instantiation solution for now.

@André Yuhai 2019-11-02 08:03:07

I wonder why I don't get any undefined reference error when I define my template function in the same .cpp file as my main(). How does the compiler know the type then? Oh! Maybe because I am using the same function in the same .cpp file which is like explicitly using it, haha? A bit late to think that but anyway I will leave my comment here.

@Moshe Rabaev 2016-07-19 01:10:05

The compiler will generate code for each template instantiation when you use a template during the compilation step. In the compilation and linking process .cpp files are converted to pure object or machine code which in them contains references or undefined symbols because the .h files that are included in your main.cpp have no implementation YET. These are ready to be linked with another object file that defines an implementation for your template and thus you have a full a.out executable.

However since templates need to be processed in the compilation step in order to generate code for each template instantiation that you define, so simply compiling a template separate from it's header file won't work because they always go hand and hand, for the very reason that each template instantiation is a whole new class literally. In a regular class you can separate .h and .cpp because .h is a blueprint of that class and the .cpp is the raw implementation so any implementation files can be compiled and linked regularly, however using templates .h is a blueprint of how the class should look not how the object should look meaning a template .cpp file isn't a raw regular implementation of a class, it's simply a blueprint for a class, so any implementation of a .h template file can't be compiled because you need something concrete to compile, templates are abstract in that sense.

Therefore templates are never separately compiled and are only compiled wherever you have a concrete instantiation in some other source file. However, the concrete instantiation needs to know the implementation of the template file, because simply modifying the typename T using a concrete type in the .h file is not going to do the job because what .cpp is there to link, I can't find it later on because remember templates are abstract and can't be compiled, so I'm forced to give the implementation right now so I know what to compile and link, and now that I have the implementation it gets linked into the enclosing source file. Basically, the moment I instantiate a template I need to create a whole new class, and I can't do that if I don't know how that class should look like when using the type I provide unless I make notice to the compiler of the template implementation, so now the compiler can replace T with my type and create a concrete class that's ready to be compiled and linked.

To sum up, templates are blueprints for how classes should look, classes are blueprints for how an object should look. I can't compile templates separate from their concrete instantiation because the compiler only compiles concrete types, in other words, templates at least in C++, is pure language abstraction. We have to de-abstract templates so to speak, and we do so by giving them a concrete type to deal with so that our template abstraction can transform into a regular class file and in turn, it can be compiled normally. Separating the template .h file and the template .cpp file is meaningless. It is nonsensical because the separation of .cpp and .h only is only where the .cpp can be compiled individually and linked individually, with templates since we can't compile them separately, because templates are an abstraction, therefore we are always forced to put the abstraction always together with the concrete instantiation where the concrete instantiation always has to know about the type being used.

Meaning typename T get's replaced during the compilation step not the linking step so if I try to compile a template without T being replaced as a concrete value type so it won't work because that's the definition of templates it's a compile-time process, and btw meta-programming is all about using this definition.

@ClarHandsome 2019-03-19 19:33:46

Another reason that it's a good idea to write both declarations and definitions in header files is for readability. Suppose there's such a template function in Utility.h:

template <class T>
T min(T const& one, T const& theOther);

And in the Utility.cpp:

#include "Utility.h"
template <class T>
T min(T const& one, T const& other)
{
    return one < other ? one : other;
}

This requires every T class here to implement the less than operator (<). It will throw a compiler error when you compare two class instances that haven't implemented the "<".

Therefore if you separate the template declaration and definition, you won't be able to only read the header file to see the ins and outs of this template in order to use this API on your own classes, though the compiler will tell you in this case about which operator needs to be overridden.

@Ni Nisan Nijackle 2019-03-11 18:38:08

You can actually define your template class inside a .template file rather than a .cpp file. Whoever is saying you can only define it inside a header file is wrong. This is something that works all the way back to c++ 98.

Don't forget to have your compiler treat your .template file as a c++ file to keep the intelli sense.

Here is an example of this for a dynamic array class.

#ifndef dynarray_h
#define dynarray_h

#include <iostream>

template <class T>
class DynArray{
    int capacity_;
    int size_;
    T* data;
public:
    explicit DynArray(int size = 0, int capacity=2);
    DynArray(const DynArray& d1);
    ~DynArray();
    T& operator[]( const int index);
    void operator=(const DynArray<T>& d1);
    int size();

    int capacity();
    void clear();

    void push_back(int n);

    void pop_back();
    T& at(const int n);
    T& back();
    T& front();
};

#include "dynarray.template" // this is how you get the header file

#endif

Now inside you .template file you define your functions just how you normally would.

template <class T>
DynArray<T>::DynArray(int size, int capacity){
    if (capacity >= size){
        this->size_ = size;
        this->capacity_ = capacity;
        data = new T[capacity];
    }
    //    for (int i = 0; i < size; ++i) {
    //        data[i] = 0;
    //    }
}

template <class T>
DynArray<T>::DynArray(const DynArray& d1){
    //clear();
    //delete [] data;
    std::cout << "copy" << std::endl;
    this->size_ = d1.size_;
    this->capacity_ = d1.capacity_;
    data = new T[capacity()];
    for(int i = 0; i < size(); ++i){
        data[i] = d1.data[i];
    }
}

template <class T>
DynArray<T>::~DynArray(){
    delete [] data;
}

template <class T>
T& DynArray<T>::operator[]( const int index){
    return at(index);
}

template <class T>
void DynArray<T>::operator=(const DynArray<T>& d1){
    if (this->size() > 0) {
        clear();
    }
    std::cout << "assign" << std::endl;
    this->size_ = d1.size_;
    this->capacity_ = d1.capacity_;
    data = new T[capacity()];
    for(int i = 0; i < size(); ++i){
        data[i] = d1.data[i];
    }

    //delete [] d1.data;
}

template <class T>
int DynArray<T>::size(){
    return size_;
}

template <class T>
int DynArray<T>::capacity(){
    return capacity_;
}

template <class T>
void DynArray<T>::clear(){
    for( int i = 0; i < size(); ++i){
        data[i] = 0;
    }
    size_ = 0;
    capacity_ = 2;
}

template <class T>
void DynArray<T>::push_back(int n){
    if (size() >= capacity()) {
        std::cout << "grow" << std::endl;
        //redo the array
        T* copy = new T[capacity_ + 40];
        for (int i = 0; i < size(); ++i) {
            copy[i] = data[i];
        }

        delete [] data;
        data = new T[ capacity_ * 2];
        for (int i = 0; i < capacity() * 2; ++i) {
            data[i] = copy[i];
        }
        delete [] copy;
        capacity_ *= 2;
    }
    data[size()] = n;
    ++size_;
}

template <class T>
void DynArray<T>::pop_back(){
    data[size()-1] = 0;
    --size_;
}

template <class T>
T& DynArray<T>::at(const int n){
    if (n >= size()) {
        throw std::runtime_error("invalid index");
    }
    return data[n];
}

template <class T>
T& DynArray<T>::back(){
    if (size() == 0) {
        throw std::runtime_error("vector is empty");
    }
    return data[size()-1];
}

template <class T>
T& DynArray<T>::front(){
    if (size() == 0) {
        throw std::runtime_error("vector is empty");
    }
    return data[0];
    }

@Tommy 2019-08-28 15:42:59

Most people would define a header file to be anything that propagates definitions to source files. So you may have decided to use the file extension ".template" but you've written a header file.

@DevSolar 2009-01-30 13:38:59

Actually, prior to C++11 the standard defined the export keyword that would make it possible to declare templates in a header file and implement them elsewhere.

None of the popular compilers implemented this keyword. The only one I know about is the frontend written by the Edison Design Group, which is used by the Comeau C++ compiler. All others required you to write templates in header files, because the compiler needs the template definition for proper instantiation (as others pointed out already).

As a result, the ISO C++ standard committee decided to remove the export feature of templates with C++11.

@DevSolar 2015-11-19 10:27:14

...and a couple of years later, I finally understood what export would actually have given us, and what not... and now I wholeheartedly agree with the EDG people: It would not have brought us what most people (myself in '11 included) think it would, and the C++ standard is better off without it.

@v.oddou 2016-04-25 09:51:02

@DevSolar : this paper is political, repetitive and badly written. that's not usual standard level prose there. Uneedingly long and boring, saying basically 3 times the same things accross tens of pages. But I am now informed that export is not export. That's a good intel !

@DevSolar 2016-04-25 09:58:18

@v.oddou: Good developer and good technical writer are two seperate skillsets. Some can do both, many can't. ;-)

@curiousguy 2019-12-14 01:20:03

@v.oddou The paper isn't just badly written, it's disinformation. Also it's a spin on reality: what are actually extremely strong arguments for exports are mixed in a way to make it sound like they are against export: “discovering numerous ODRrelated holes in the standard in the presence of export. Before export, ODR violations didn’t have to be diagnosed by the compiler. Now it’s necessary because you need to combine internal data structures from different translation units, and you can’t combine them if they’re actually representing different things, so you need to do the checking.”

@curiousguy 2019-12-14 01:35:41

"must now add which translation unit it was in when it happened" Duh. When you're forced to use arguments that lame, you don't have any argument. Of course you are going to mention file names in your errors, what's the deal? That anyone falls for that BS is mind boggling. "Even experts like James Kanze find it hard to accept that export really is like this." WHAT?!!!!

@Nikos 2018-07-19 00:49:05

Just to add something noteworthy here. One can define methods of a templated class just fine in the implementation file when they are not function templates.


myQueue.hpp:

template <class T> 
class QueueA {
    int size;
    ...
public:
    template <class T> T dequeue() {
       // implementation here
    }

    bool isEmpty();

    ...
}    

myQueue.cpp:

// implementation of regular methods goes like this:
template <class T> bool QueueA<T>::isEmpty() {
    return this->size == 0;
}


main()
{
    QueueA<char> Q;

    ...
}

@Pranay 2017-05-13 01:42:11

A way to have separate implementation is as follows.

//inner_foo.h

template <typename T>
struct Foo
{
    void doSomething(T param);
};


//foo.tpp
#include "inner_foo.h"
template <typename T>
void Foo<T>::doSomething(T param)
{
    //implementation
}


//foo.h
#include <foo.tpp>

//main.cpp
#include <foo.h>

inner_foo has the forward declarations. foo.tpp has the implementation and include inner_foo.h; and foo.h will have just one line, to include foo.tpp.

On compile time, contents of foo.h are copied to foo.tpp and then the whole file is copied to foo.h after which it compiles. This way, there is no limitations, and the naming is consistent, in exchange for one extra file.

I do this because static analyzers for the code break when it does not see the forward declarations of class in *.tpp. This is annoying when writing code in any IDE or using YouCompleteMe or others.

@user246672 2019-01-23 05:19:33

s/inner_foo/foo/g and include foo.tpp at the end of foo.h. One less file.

@David Hanak 2009-01-30 10:23:36

Templates need to be instantiated by the compiler before actually compiling them into object code. This instantiation can only be achieved if the template arguments are known. Now imagine a scenario where a template function is declared in a.h, defined in a.cpp and used in b.cpp. When a.cpp is compiled, it is not necessarily known that the upcoming compilation b.cpp will require an instance of the template, let alone which specific instance would that be. For more header and source files, the situation can quickly get more complicated.

One can argue that compilers can be made smarter to "look ahead" for all uses of the template, but I'm sure that it wouldn't be difficult to create recursive or otherwise complicated scenarios. AFAIK, compilers don't do such look aheads. As Anton pointed out, some compilers support explicit export declarations of template instantiations, but not all compilers support it (yet?).

@vava 2009-01-30 10:27:49

"export" is standard, but it's just hard to implement so most of the compiler teams just haven't done yet.

@Pieter 2009-01-30 15:13:33

export doesn't eliminate the need for source disclosure, nor does it reduce compile dependencies, while it requires a massive effort from compiler builders. So Herb Sutter himself asked compiler builders to 'forget about' export. As the time investment needed would be better spend elsewhere...

@Pieter 2009-01-30 15:14:33

So I don't think export isn't implemented 'yet'. It'll probably never get done by anyone else than EDG after the others saw how long it took, and how little was gained

@Pieter 2009-01-30 15:22:13

If that interests you, the paper is called "Why we can't afford export", it's listed on his blog (gotw.ca/publications) but no pdf there (a quick google should turn it up though)

@Vlad 2013-10-11 17:54:00

Ok, thanks for good example and explanation. Here is my question though: why compiler cannot figure out where template is called, and compile those files first before compiling definition file? I can imagine it can be done in a simple case... Is the answer that interdependencies will mess up the order pretty fast?

@ajeh 2018-04-02 18:49:53

"When a.cpp is compiled, it is not necessarily known that the upcoming compilation b.cpp will require an instance of the template, let alone which specific instance would that be." This cluster F is by design, in other words.

@L. F. 2019-09-16 13:50:37

@vava The export keyword is actually reused in C++20, although for a completely different meaning ...

@Eric Shaw 2016-07-27 05:01:10

If the concern is the extra compilation time and binary size bloat produced by compiling the .h as part of all the .cpp modules using it, in many cases what you can do is make the template class descend from a non-templatized base class for non type-dependent parts of the interface, and that base class can have its implementation in the .cpp file.

@Fabio A. 2016-11-04 08:38:05

This response should be modded up quite more. I "independently" discovered your same approach and was specifically looking for somebody else to have used it already, since I'm curious if it's an official pattern and whether it's got a name. My approach is to implement a class XBase wherever I need to implement a template class X, putting the type-dependent parts in X and all the rest in XBase.

@lafrecciablu 2016-05-12 14:02:10

Even though there are plenty of good explanations above, I'm missing a practical way to separate templates into header and body.
My main concern is avoiding recompilation of all template users, when I change its definition.
Having all template instantiations in the template body is not a viable solution for me, since the template author may not know all if its usage and the template user may not have the right to modify it.
I took the following approach, which works also for older compilers (gcc 4.3.4, aCC A.03.13).

For each template usage there's a typedef in its own header file (generated from the UML model). Its body contains the instantiation (which ends up in a library which is linked in at the end).
Each user of the template includes that header file and uses the typedef.

A schematic example:

MyTemplate.h:

#ifndef MyTemplate_h
#define MyTemplate_h 1

template <class T>
class MyTemplate
{
public:
  MyTemplate(const T& rt);
  void dump();
  T t;
};

#endif

MyTemplate.cpp:

#include "MyTemplate.h"
#include <iostream>

template <class T>
MyTemplate<T>::MyTemplate(const T& rt)
: t(rt)
{
}

template <class T>
void MyTemplate<T>::dump()
{
  cerr << t << endl;
}

MyInstantiatedTemplate.h:

#ifndef MyInstantiatedTemplate_h
#define MyInstantiatedTemplate_h 1
#include "MyTemplate.h"

typedef MyTemplate< int > MyInstantiatedTemplate;

#endif

MyInstantiatedTemplate.cpp:

#include "MyTemplate.cpp"

template class MyTemplate< int >;

main.cpp:

#include "MyInstantiatedTemplate.h"

int main()
{
  MyInstantiatedTemplate m(100);
  m.dump();
  return 0;
}

This way only the template instantiations will need to be recompiled, not all template users (and dependencies).

@Cameron Tacklind 2019-02-16 08:55:08

I like this approach with the exception of the MyInstantiatedTemplate.h file and added MyInstantiatedTemplate type. It's a little cleaner if you don't use that, imho. Checkout my answer on a different question showing this: stackoverflow.com/a/41292751/4612476

@Wormer 2019-10-30 20:10:41

This takes best of two worlds. I wish this answer was rated higher! Also see the link above for a slightly cleaner implementation of the same idea.

@Anton Gogolev 2009-01-30 10:15:20

Although standard C++ has no such requirement, some compilers require that all function and class templates need to be made available in every translation unit they are used. In effect, for those compilers, the bodies of template functions must be made available in a header file. To repeat: that means those compilers won't allow them to be defined in non-header files such as .cpp files

There is an export keyword which is supposed to mitigate this problem, but it's nowhere close to being portable.

@MainID 2009-01-30 10:20:06

Why can't I implement them in .cpp file with the keyword "inline"?

@vava 2009-01-30 10:28:59

You can, and you don't have to put "inline" even. But you'd be able to use them just in that cpp file and nowhere else.

@Lightness Races with Monica 2011-08-14 17:59:08

This is almost the most accurate answer, except "that means those compilers won't allow them to be defined in non-header files such as .cpp files" is patently false.

@Germán Diago 2013-05-12 16:42:41

Templates must be used in headers because the compiler needs to instantiate different versions of the code, depending on the parameters given/deduced for template parameters. Remember that a template doesn't represent code directly, but a template for several versions of that code. When you compile a non-template function in a .cpp file, you are compiling a concrete function/class. This is not the case for templates, which can be instantiated with different types, namely, concrete code must be emitted when replacing template parameters with concrete types.

There was a feature with the export keyword that was meant to be used for separate compilation. The export feature is deprecated in C++11 and, AFAIK, only one compiler implemented it. You shouldn't make use of export. Separate compilation is not possible in C++ or C++11 but maybe in C++17, if concepts make it in, we could have some way of separate compilation.

For separate compilation to be achieved, separate template body checking must be possible. It seems that a solution is possible with concepts. Take a look at this paper recently presented at the standards commitee meeting. I think this is not the only requirement, since you still need to instantiate code for the template code in user code.

The separate compilation problem for templates I guess it's also a problem that is arising with the migration to modules, which is currently being worked.

@Ben 2013-05-11 03:54:29

It's because of the requirement for separate compilation and because templates are instantiation-style polymorphism.

Lets get a little closer to concrete for an explanation. Say I've got the following files:

  • foo.h
    • declares the interface of class MyClass<T>
  • foo.cpp
    • defines the implementation of class MyClass<T>
  • bar.cpp
    • uses MyClass<int>

Separate compilation means I should be able to compile foo.cpp independently from bar.cpp. The compiler does all the hard work of analysis, optimization, and code generation on each compilation unit completely independently; we don't need to do whole-program analysis. It's only the linker that needs to handle the entire program at once, and the linker's job is substantially easier.

bar.cpp doesn't even need to exist when I compile foo.cpp, but I should still be able to link the foo.o I already had together with the bar.o I've only just produced, without needing to recompile foo.cpp. foo.cpp could even be compiled into a dynamic library, distributed somewhere else without foo.cpp, and linked with code they write years after I wrote foo.cpp.

"Instantiation-style polymorphism" means that the template MyClass<T> isn't really a generic class that can be compiled to code that can work for any value of T. That would add overhead such as boxing, needing to pass function pointers to allocators and constructors, etc. The intention of C++ templates is to avoid having to write nearly identical class MyClass_int, class MyClass_float, etc, but to still be able to end up with compiled code that is mostly as if we had written each version separately. So a template is literally a template; a class template is not a class, it's a recipe for creating a new class for each T we encounter. A template cannot be compiled into code, only the result of instantiating the template can be compiled.

So when foo.cpp is compiled, the compiler can't see bar.cpp to know that MyClass<int> is needed. It can see the template MyClass<T>, but it can't emit code for that (it's a template, not a class). And when bar.cpp is compiled, the compiler can see that it needs to create a MyClass<int>, but it can't see the template MyClass<T> (only its interface in foo.h) so it can't create it.

If foo.cpp itself uses MyClass<int>, then code for that will be generated while compiling foo.cpp, so when bar.o is linked to foo.o they can be hooked up and will work. We can use that fact to allow a finite set of template instantiations to be implemented in a .cpp file by writing a single template. But there's no way for bar.cpp to use the template as a template and instantiate it on whatever types it likes; it can only use pre-existing versions of the templated class that the author of foo.cpp thought to provide.

You might think that when compiling a template the compiler should "generate all versions", with the ones that are never used being filtered out during linking. Aside from the huge overhead and the extreme difficulties such an approach would face because "type modifier" features like pointers and arrays allow even just the built-in types to give rise to an infinite number of types, what happens when I now extend my program by adding:

  • baz.cpp
    • declares and implements class BazPrivate, and uses MyClass<BazPrivate>

There is no possible way that this could work unless we either

  1. Have to recompile foo.cpp every time we change any other file in the program, in case it added a new novel instantiation of MyClass<T>
  2. Require that baz.cpp contains (possibly via header includes) the full template of MyClass<T>, so that the compiler can generate MyClass<BazPrivate> during compilation of baz.cpp.

Nobody likes (1), because whole-program-analysis compilation systems take forever to compile , and because it makes it impossible to distribute compiled libraries without the source code. So we have (2) instead.

@v.oddou 2016-04-25 09:57:02

emphasized quote a template is literally a template; a class template is not a class, it's a recipe for creating a new class for each T we encounter

@gromit190 2017-03-09 08:01:33

I'd like to know, is it possible to do the explicit instantiations from somewhere other than the class' header or source file? For instance, do them in main.cpp?

@Ben 2017-03-09 11:02:19

@Birger You should be able to do it from any file that has access to the full template implementation (either because it's in the same file or via header includes).

@ajeh 2018-04-02 18:48:14

How's this an answer? It provides no solution but rhetoric only.

@Ben 2018-04-02 22:02:33

@ajeh It's not rhetoric. The question is "why do you have to implement templates in a header?", so I explained the technical choices the C++ language makes that lead to this requirement. Before I wrote my answer others already provided workarounds that are not full solutions, because there can't be a full solution. I felt those answers would be complemented by a fuller discussion of the "why" angle of the question.

@Puddle 2018-11-27 00:01:42

imagine it this way folks... if you weren't using templates (to efficiently code what you needed), you'd only be offering a few versions of that class anyway. so you have 3 options. 1). don't use templates. (like all other classes/functions, nobody cares that others can't alter the types) 2). use templates, and document which types they can use. 3). give them the whole implementation (source) bonus 4). give them the whole source in case they want to make a template from another one of your classes ;)

@MaHuJa 2009-08-13 13:49:17

Plenty correct answers here, but I wanted to add this (for completeness):

If you, at the bottom of the implementation cpp file, do explicit instantiation of all the types the template will be used with, the linker will be able to find them as usual.

Edit: Adding example of explicit template instantiation. Used after the template has been defined, and all member functions has been defined.

template class vector<int>;

This will instantiate (and thus make available to the linker) the class and all its member functions (only). Similar syntax works for template functions, so if you have non-member operator overloads you may need to do the same for those.

The above example is fairly useless since vector is fully defined in headers, except when a common include file (precompiled header?) uses extern template class vector<int> so as to keep it from instantiating it in all the other (1000?) files that use vector.

@Jiminion 2014-07-17 17:49:29

Ugh. Good answer, but no real clean solution. Listing out all possible types for a template does not seem to go with what a template is supposed to be.

@Tomáš Zato - Reinstate Monica 2014-12-09 03:27:38

This can be good in many cases but generally breaks the purpose of template which is meant to allow you to use the class with any type without manually listing them.

@UncleZeiv 2015-06-03 15:41:06

vector is not a good example because a container is inherently targeting "all" types. But it does happen very frequently that you create templates that are only meant for a specific set of types, for instance numeric types: int8_t, int16_t, int32_t, uint8_t, uint16_t, etc. In this case, it still makes sense to use a template, but explicitly instantiating them for the whole set of types is also possible and, in my opinion, recommended.

@Vitt Volt 2017-02-16 06:04:30

Used after the template has been defined, "and all member functions has been defined". Thanks !

@gromit190 2017-03-09 08:01:21

I'd like to know, is it possible to do the explicit instantiations from somewhere other than the class' header or source file? For instance, do them in main.cpp?

@Miral 2017-04-20 06:23:36

Explicit instantiations must be in a place where the implementation of the template methods is visible. If your implementations are in a cpp file, then (without silliness) you can only explicitly instantiate in that same cpp file, not in any other cpp file.

@oarfish 2019-09-04 14:38:38

I feel like I'm missing something … I put the explicit instantiation for two types into the class's .cpp file and the two instantiations are referred to from other .cpp files, and I still get the linking error that the members are not found.

@Robert 2011-09-17 03:40:18

That is exactly correct because the compiler has to know what type it is for allocation. So template classes, functions, enums,etc.. must be implemented as well in the header file if it is to be made public or part of a library (static or dynamic) because header files are NOT compiled unlike the c/cpp files which are. If the compiler doesn't know the type is can't compile it. In .Net it can because all objects derive from the Object class. This is not .Net.

@Flexo 2011-09-17 12:26:52

"header files are NOT compiled" - that's a really odd way of describing it. Header files can be part of a translation unit, just like a "c/cpp" file.

@xaxxon 2015-12-21 22:46:56

In fact, it's almost the opposite of the truth, which is that header files are very frequently compiled many times, whereas a source file is usually compiled once.

@Benoît 2009-01-30 10:53:32

It means that the most portable way to define method implementations of template classes is to define them inside the template class definition.

template < typename ... >
class MyClass
{

    int myMethod()
    {
       // Not just declaration. Add method implementation here
    }
};

Related Questions

Sponsored Content

17 Answered Questions

[SOLVED] What should main() return in C and C++?

8 Answered Questions

[SOLVED] Why are C++ inline functions in the header?

12 Answered Questions

[SOLVED] Storing C++ template function definitions in a .CPP file

  • 2008-09-22 15:55:52
  • Rob
  • 313326 View
  • 489 Score
  • 12 Answer
  • Tags:   c++ templates

24 Answered Questions

[SOLVED] Image Processing: Algorithm Improvement for 'Coca-Cola Can' Recognition

6 Answered Questions

10 Answered Questions

[SOLVED] Unnamed/anonymous namespaces vs. static functions

  • 2008-09-30 19:02:00
  • Head Geek
  • 200733 View
  • 486 Score
  • 10 Answer
  • Tags:   c++ namespaces

17 Answered Questions

[SOLVED] Fastest way to check if a file exist using standard C++/C++11/C?

  • 2012-10-08 01:10:11
  • Vincent
  • 568737 View
  • 410 Score
  • 17 Answer
  • Tags:   c++ c file stream

2 Answered Questions

[SOLVED] How to implement classic sorting algorithms in modern C++?

13 Answered Questions

[SOLVED] Why is the C++ STL is so heavily based on templates? (and not on *interfaces*)

Sponsored Content