PAYATHON 2026

如何分发使用 C++ modules 的动态库(无头文件)

数据小陈

目前没有一个由 ISO 或 CMake 统一规定、能跨编译器和构建系统的 C++ modules 动态库分发标准。比较现实的半标准做法是分发“模块接口源文件 + 动态库二进制 + 构建系统元数据”,让消费者在自己的构建中使用匹配的工具链和 ABI 配置生成 BMI。CMake 的 FILE_SET CXX_MODULES、install/export 和导入目标可以作为元数据载体,但具体支持程度随 CMake 版本和生成器变化。

为什么不能直接照搬 headers + dll/so

传统 headers + dll/so 的分发方式,核心是头文件只包含声明和模板/内联定义,二进制库提供实现,消费者用自己的编译器编译头文件并链接二进制库。C++ modules 下,对外接口通常对应模块接口单元,例如 foo.cppm 或 foo.ixx。这个文件仍然是源码,不是 BMI;消费者需要用自己的编译器把它编译成 BMI,然后才能 import foo;。BMI 的格式、模块名映射、命令行细节和 ABI 细节由编译器实现决定,不是 C++ 标准保证的可移植产物。

因此,不建议把 BMI 当作像头文件那样公开分发的唯一接口。更稳妥的做法是把模块接口源文件作为公开接口的一部分,把动态库二进制作为实现,把链接依赖、编译选项、模块文件列表等交给构建系统元数据描述。

推荐的分发形态

一个可落地的安装布局大致如下:

prefix/
  include/foo/cxx-modules/foo.cppm
  lib/libfoo.so
  lib/cmake/foo/fooConfig.cmake
  lib/cmake/foo/fooTargets.cmake

消费者拿到的是模块接口源文件、动态库和 CMake 导入目标。消费者构建时,CMake 或手写构建规则用同一编译器家族、同一 C++ 标准、兼容的 ABI 选项编译 foo.cppm 生成 BMI,再链接 libfoo.so。这样虽然不再是“无源码接口”,但它是目前最接近传统 headers + dll/so 的半标准形态。

CMake 示例:库侧

下面只是示意,实际写法要以你使用的 CMake 版本和生成器支持为准:

cmake_minimum_required(VERSION 3.28) # 仅示意,按实际版本能力调整
project(foo LANGUAGES CXX)

add_library(foo SHARED)
target_sources(foo
  PUBLIC
    FILE_SET CXX_MODULES FILES
      src/foo.cppm
)
target_sources(foo PRIVATE src/foo_impl.cpp)
target_compile_features(foo PUBLIC cxx_std_20)
target_include_directories(foo PUBLIC
  $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src>
  $<INSTALL_INTERFACE:include/foo/cxx-modules>
)

install(TARGETS foo
  EXPORT fooTargets
  FILE_SET CXX_MODULES DESTINATION include/foo/cxx-modules
  RUNTIME DESTINATION bin
  LIBRARY DESTINATION lib
  ARCHIVE DESTINATION lib
)
install(EXPORT fooTargets
  NAMESPACE foo::
  DESTINATION lib/cmake/foo
)

模块接口单元可以保持只导出声明:

// src/foo.cppm
export module foo;

export namespace foo {
    void hello();
}

实现放在普通实现文件或模块实现单元中:

// src/foo_impl.cpp
module;
#include <cstdio>
module foo;

namespace foo {
    void hello() { std::puts("hello"); }
}

消费者侧

消费者通过导入目标使用库:

find_package(foo CONFIG REQUIRED)
add_executable(app app.cpp)
target_link_libraries(app PRIVATE foo::foo)
// app.cpp
import foo;

int main() {
    foo::hello();
}

如果不是 CMake 构建系统,就需要在文档中明确列出:模块接口文件列表、模块名、include 目录、需要链接的库、启用 C++20 modules 的编译选项,以及必须保持一致的 ABI 相关宏和编译选项。pkg-config 可以传递 -I、-L、-l 等信息,但它本身不理解模块接口编译语义,不能单独承担 modules 分发。

注意事项

模块接口源文件不是头文件,但它仍然是公开接口源码。若业务上不能暴露接口源码,就只能把 BMI 与二进制库绑定到固定编译器、固定标准库、固定编译选项上分发,可移植性会很差。

消费者和库作者应尽量保持编译器家族、主版本、C++ 标准、标准库和影响 ABI 的宏一致。模块能解决声明暴露方式的问题,但不能消除 C++ ABI 和工具链差异。

模块接口文件、动态库和导入目标应一起安装、一起版本化。只给 .so 或只给 BMI 都不够稳。

如果必须支持多种编译器,优先分发模块接口源码,让各工具链各自生成 BMI;不要试图提供一个跨编译器的 BMI 包。

备注:内容仅供参考。