模板函数(template function)出现编译链接错误(link error)之解析

总的结论：

   将template function 或者 template class的完整定义直接放在.h文件中，然后加到要使用这些template function的.cpp文件中。

1. 现象描述

类似于参考文献[1]，当我们以如下方式使用模板函数时，会出现模板函数声明、定义分离带来的链接错误：

 // File "foo.h"
 template<typename T>
 extern void foo();

 // File "foo.cpp"
 #include <iostream>
 #include "foo.h"

 template<typename T>
 void foo()
 {
   std::cout << "Here I am!\n";
 }

使用时：

 // File "main.cpp"
 #include "foo.h"

 int main()
 {
   foo<int>();
   ...
 }

在如此使用时，会报出link error.

通常来说有两种解决办法：

（1）将template function 或者 template class的完整定义直接放在.h文件中，然后加到要使用这些template function的.cpp文件中（当然，此法的确定是，对某些编译器而言，会造成最后生成的.exe文件比较大）；

 （2）在.cpp文件中定义模板函数的时候，就将模板函数先实例化，例如：

 // File "foo.cpp"
 #include <iostream>
 #include "foo.h"

 template<typename T> void foo()
 {
   std::cout << "Here I am!\n";
 }

 template void foo<int>();

或者：把.cpp文件当成头文件一样加入到需要使用模板函数的.cpp文件中：

 // File "main.cpp"
 #include "foo.cpp"//有可能会有点令人迷惑---这是本方法的缺点
 template void foo<int>();

 int main()
 {
   foo<int>();
   ...
 }

2.原理说明

　　参考文献[3]中已经有很好的说明，此处仅转载之。

上面问题不知道怎么解决,就开始google解决方案: 模板不支持分离编译, 把你模板类的声明和实现放到.h文件里面 。按照这个说的把.h和.cpp文件合并后，果然可以了。

但是为什么呢，为什么模板就不支持分离编译？---继续google ing

搜到了如下文章（文章原文链接：http://blog.csdn.net/bichenggui/article/details/4207084）：

首先，一个编译单元（translation unit）是指一个.cpp文件以及它所#include的所有.h文件，.h文件里的代码将会被扩展到包含它的.cpp文件里，然后编译器编译该.cpp文件为一个.obj文件（假定我们的平台是win32），后者拥有PE（Portable Executable，即windows可执行文件）文件格式，并且本身包含的就已经是二进制码，但是不一定能够执行，因为并不保证其中一定有main函数。当编译器将一个工程里的所有.cpp文件以分离的方式编译完毕后，再由连接器（linker）进行连接成为一个.exe文件。

举个例子：

//---------------test.h-------------------//

 

void f();//这里声明一个函数f

 

//---------------test.cpp--------------//

 

#include”test.h”

 

void f()

 

{

 

…//do something

 

} //这里实现出test.h中声明的f函数

 

//---------------main.cpp--------------//

 

#include”test.h”

 

int main()

 

{

 

f(); //调用f，f具有外部连接类型

 

}

在这个例子中，test. cpp和main.cpp各自被编译成不同的.obj文件（姑且命名为test.obj和main.obj），在main.cpp中，调用了f函数，然而当编译器编译main.cpp时，它所仅仅知道的只是main.cpp中所包含的test.h文件中的一个关于void f();的声明，所以，编译器将这里的f看作外部连接类型，即认为它的函数实现代码在另一个.obj文件中，本例也就是test.obj，也就是说，main.obj中实际没有关于f函数的哪怕一行二进制代码，而这些代码实际存在于test.cpp所编译成的test.obj中。在main.obj中对f的调用只会生成一行call指令，像这样：

call f [C++中这个名字当然是经过mangling[处理]过的]

在编译时，这个call指令显然是错误的，因为main.obj中并无一行f的实现代码。那怎么办呢？这就是连接器的任务，连接器负责在其它的.obj中（本例为test.obj）寻找f的实现代码，找到以后将call f这个指令的调用地址换成实际的f的函数进入点地址。需要注意的是：连接器实际上将工程里的.obj“连接”成了一个.exe文件，而它最关键的任务就是上面说的，寻找一个外部连接符号在另一个.obj中的地址，然后替换原来的“虚假”地址。

这个过程如果说的更深入就是：

call f这行指令其实并不是这样的，它实际上是所谓的stub，也就是一个jmp 0xABCDEF。这个地址可能是任意的，然而关键是这个地址上有一行指令来进行真正的call f动作。也就是说，这个.obj文件里面所有对f的调用都jmp向同一个地址，在后者那儿才真正”call”f。这样做的好处就是连接器修改地址时只要对后者的call XXX地址作改动就行了。但是，连接器是如何找到f的实际地址的呢（在本例中这处于test.obj中），因为.obj与.exe的格式是一样的，在这样的文件中有一个符号导入表和符号导出表（import table和export table）其中将所有符号和它们的地址关联起来。这样连接器只要在test.obj的符号导出表中寻找符号f（当然C++对f作了mangling）的地址就行了，然后作一些偏移量处理后（因为是将两个.obj文件合并，当然地址会有一定的偏移，这个连接器清楚）写入main.obj中的符号导入表中f所占有的那一项即可。

这就是大概的过程。其中关键就是：

编译main.cpp时，编译器不知道f的实现，所以当碰到对它的调用时只是给出一个指示，指示连接器应该为它寻找f的实现体。这也就是说main.obj中没有关于f的任何一行二进制代码。

编译test.cpp时，编译器找到了f的实现。于是乎f的实现（二进制代码）出现在test.obj里。

连接时，连接器在test.obj中找到f的实现代码（二进制）的地址（通过符号导出表）。然后将main.obj中悬而未决的call XXX地址改成f实际的地址。完成。

然而，对于模板，你知道，模板函数的代码其实并不能直接编译成二进制代码，其中要有一个“实例化”的过程。举个例子：

//----------main.cpp------//

 

template<class T>

 

void f(T t)

 

{}

 

int main()

 

{

 

…//do something

 

f(10); // call f<int> 编译器在这里决定给f一个f<int>的实例

 

…//do other thing

 

}

也就是说，如果你在main.cpp文件中没有调用过f，f也就得不到实例化，从而main.obj中也就没有关于f的任意一行二进制代码！如果你这样调用了：

f(10); // f<int>得以实例化出来

f(10.0); // f<double>得以实例化出来

这样main.obj中也就有了f<int>，f<double>两个函数的二进制代码段。以此类推。

然而实例化要求编译器知道模板的定义，不是吗？

看下面的例子（将模板的声明和实现分离）：

//-------------test.h----------------//

 

template<class T>

 

class A

 

{

 

public:

 

void f(); // 这里只是个声明

 

};

 

//---------------test.cpp-------------//

 

#include”test.h”

 

template<class T>

 

void A<T>::f() // 模板的实现

 

{

 

…//do something

 

}

 

//---------------main.cpp---------------//

 

#include”test.h”

 

int main()

 

{

 

A<int> a;

 

f(); // #1

 

}

编译器在#1处并不知道A<int>::f的定义，因为它不在test.h里面，于是编译器只好寄希望于连接器，希望它能够在其他.obj里面找到A<int>::f的实例，在本例中就是test.obj，然而，后者中真有A<int>::f的二进制代码吗？NO！！！因为C++标准明确表示，当一个模板不被用到的时侯它就不该被实例化出来，test.cpp中用到了A<int>::f了吗？没有！！所以实际上test.cpp编译出来的test.obj文件中关于A::f一行二进制代码也没有，于是连接器就傻眼了，只好给出一个连接错误。但是，如果在test.cpp中写一个函数，其中调用A<int>::f，则编译器会将其实例化出来，因为在这个点上（test.cpp中），编译器知道模板的定义，所以能够实例化，于是，test.obj的符号导出表中就有了A<int>::f这个符号的地址，于是连接器就能够完成任务。

关键是：在分离式编译的环境下，编译器编译某一个.cpp文件时并不知道另一个.cpp文件的存在，也不会去查找（当遇到未决符号时它会寄希望于连接器）。这种模式在没有模板的情况下运行良好，但遇到模板时就傻眼了，因为模板仅在需要的时候才会实例化出来，所以，当编译器只看到模板的声明时，它不能实例化该模板，只能创建一个具有外部连接的符号并期待连接器能够将符号的地址决议出来。然而当实现该模板的.cpp文件中没有用到模板的实例时，编译器懒得去实例化，所以，整个工程的.obj中就找不到一行模板实例的二进制代码，于是连接器也黔驴技穷了。

Reference

[1]  How can I avoid linker errors with my template functions?  http://www.parashift.com/c++-faq/separate-template-fn-defn-from-decl.html

[2]  C++ template, linking error.http://stackoverflow.com/questions/1353973/c-template-linking-error

[3]  c++模板函数声明定义分离编译错误详解. http://www.cnblogs.com/qlwy/archive/2012/03/21/2410045.html