构建共享库时，显式实例化模板的EXPORT语句应置于何处？

场景背景 #

我正在构建一个共享库，CMake中设置了：

set(CMAKE_CXX_VISIBILITY_PRESET hidden)

因此必须手动导出公共API。现有一个拆分到两个文件的模板类：

• my_lib.hpp仅包含声明：

  template <typename Scalar>
  class MyLibClass { ... };
  

• my_lib.cpp包含实现和显式实例化：

  ...
  template class MyLibClass<float>;
  template class MyLibClass<double>;
  

使用CMake的generate_export_header()生成了my_lib_export.hpp，里面包含对应的导出声明，目前有两种使用方式：

方式一：修饰头文件中的模板类声明 #

在my_lib.hpp中添加导出宏：

#include "my_lib_export.hpp"
template <typename Scalar>
class MY_LIB_EXPORT MyLibClass { ... };

方式二：修饰实现文件中的显式实例化语句 #

在my_lib.cpp中给显式实例化添加导出宏：

#include "my_lib_export.hpp"
...
template class MY_LIB_EXPORT MyLibClass<float>;
template class MY_LIB_EXPORT MyLibClass<double>;

两种方式在简单示例中都能正常编译链接，想了解二者是否存在区别、用途不同还是完全可互换？

区别与适用场景 #

这两种方式并非完全可互换，核心区别在于对模板实体可见性的控制范围：

• 方式一：修饰模板声明

  • 效果：将整个模板的所有实例化（包括显式、隐式实例化）都标记为需要导出的公共API。
  • 风险：如果用户在使用库时对未显式实例化的类型（比如int）进行隐式实例化，链接器会尝试寻找该实例的符号，但库中并未提供，会出现链接错误。
  • 适用场景：仅当你希望允许用户自行实例化模板的任意类型时使用，但这种场景下通常不会把模板实现放在cpp文件中（因为用户无法完成隐式实例化），所以这种方式和你当前的场景并不匹配。

• 方式二：修饰显式实例化

  • 效果：仅将显式指定的那几个模板实例（float、double版本）标记为导出的公共API，模板本身的声明仍然是隐藏可见性。
  • 优势：严格控制了库对外暴露的实例类型，避免用户尝试实例化未提供的类型导致链接错误，完全贴合你把模板实现封装在库内部、仅提供特定显式实例的场景。
  • 适用场景：就是你当前的场景——模板实现放在cpp文件中，仅对外暴露预先实例化好的特定类型版本。

简单来说，方式二是你这种场景下的正确做法，方式一虽然能编译，但会带来不必要的风险和语义混淆。

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