编译含模板函数的C++多文件工程出现undefined reference错误求助

问题场景 #

存在以下3个源文件：

main.cpp #

#include <iostream>
#include <string>
#include <vector>

#include "funcs.hpp"

void possible_characters(std::string &digits) {
  std::vector<std::string> res;
  
  print_vec(res);
}

int main() {
  std::string ss = "2";
  possible_characters(ss);

  return 0;
}

funcs.hpp #

#include <vector>

template <typename T> void print_vec(std::vector<T> &v);

funcs.cpp #

#include "funcs.hpp"

template <typename T> void print_vec(std::vector<T> &v) {
  for (auto &x : v) {
    std::cout << x << ", ";
  }
  std::cout << std::endl;
}

使用编译命令：

g++ main.cpp funcs.cpp -o tele_digit

出现链接错误：

undefined reference to `void print_vec<std::basic_string<char, std::char_traits, std::allocator>>(std::vector<std::basic_string<char, std::char_traits, std::allocator>, std::allocator<std::basic_string<char, std::char_traits, std::allocator>>>&)'

错误原因 #

C++模板函数的实例化是按需进行的：编译器只有在看到具体的模板参数调用时，才会生成对应的函数机器码。

这个场景下的问题链：

1. 编译funcs.cpp时，编译器仅看到模板的定义，但没有任何地方调用print_vec的具体实例（比如print_vec<std::string>），因此不会生成该模板实例的机器码。
2. 编译main.cpp时，编译器看到print_vec(res)的调用（此处res是std::vector<std::string>，模板参数T为std::string），但只有print_vec的声明没有定义，会期望链接阶段找到对应实例的机器码。
3. 链接阶段找不到匹配的模板实例代码，因此抛出"未定义引用"错误。

解决方法 #

有两种常用的修复方式：

方法1：将模板函数定义移至头文件 #

修改funcs.hpp，把模板函数的实现直接写入头文件，替代原有的声明：

#include <vector>
#include <iostream>  // 需添加该头文件，因为用到了std::cout

template <typename T> void print_vec(std::vector<T> &v) {
  for (auto &x : v) {
    std::cout << x << ", ";
  }
  std::cout << std::endl;
}

之后删除funcs.cpp文件，编译命令改为：

g++ main.cpp -o tele_digit

这样main.cpp包含头文件时，编译器能获取模板的完整定义，调用时直接生成对应实例的代码，链接阶段不会出错。

方法2：在模板定义文件中显式实例化所需版本 #

如果坚持将模板定义放在.cpp文件中，可在funcs.cpp末尾显式实例化需要用到的模板参数版本：

#include "funcs.hpp"
#include <iostream>  // 添加该头文件

template <typename T> void print_vec(std::vector<T> &v) {
  for (auto &x : v) {
    std::cout << x << ", ";
  }
  std::cout << std::endl;
}

// 显式实例化std::string版本的print_vec
template void print_vec<std::string>(std::vector<std::string> &v);

编译funcs.cpp时，编译器会生成该显式实例化的机器码，链接阶段就能找到对应的函数实现。

内容的提问来源于stack exchange，提问作者Lionnel104