UNITY_BUILD¶
3.16 版新增。
当此属性设置为 true 时,目标源文件将被合并成批次以加快编译速度。这是通过创建(一组)统一源文件来完成的,这些源文件 #include
原始源文件,然后编译这些统一源文件而不是原始源文件。这被称为“统一构建”(_Unity_ build)或“巨型构建”(_Jumbo_ build)。
CMake 提供不同的算法来选择哪些源文件被分组到一个“桶”(_bucket_)中。算法选择由 UNITY_BUILD_MODE
目标属性决定,该属性具有以下可接受的值:
BATCH
在此模式下,CMake 决定哪些文件被分组在一起。UNITY_BUILD_BATCH_SIZE
属性控制每个统一源文件可以合并的源文件数量上限。GROUP
在此模式下,每个目标显式指定如何分组源文件。每个具有相同UNITY_GROUP
值的源文件将被分组在一起。任何没有此属性的源文件将单独编译。使用此模式时,UNITY_BUILD_BATCH_SIZE
属性将被忽略。
如果没有指定显式的 UNITY_BUILD_MODE
,CMake 将默认为 BATCH
。
统一构建支持以下语言:
C
3.16 版新增。
CXX
3.16 版新增。
CUDA
在版本 3.31 中添加。
OBJC
在版本 3.29 中添加。
OBJCXX
在版本 3.29 中添加。
对于混合了多种语言源文件的目标,CMake 会将语言分开,使得每个生成的统一源文件只包含单一语言的源文件。
此属性在创建目标时由 CMAKE_UNITY_BUILD
变量的值初始化。
注意
项目不应直接将 UNITY_BUILD
属性或其相关的 CMAKE_UNITY_BUILD
变量设置为 true。根据构建机器和所用编译器的能力,启用统一构建可能合适也可能不合适。因此,此功能应由开发人员控制,通常通过开发人员选择是否在 CMAKE_UNITY_BUILD
命令行或其它等效方法上设置 cmake(1)
变量来实现。然而,如果已知为目标启用统一构建会导致问题,则建议将 UNITY_BUILD
目标属性设置为 false。
ODR(单定义规则)错误¶
当多个源文件被包含到一个源文件中时,如统一构建中所示,这可能会导致 ODR 错误。CMake 提供了许多措施来帮助解决这些问题:
任何具有非空
COMPILE_OPTIONS
、COMPILE_DEFINITIONS
、COMPILE_FLAGS
或INCLUDE_DIRECTORIES
源属性的源文件将不会被合并到统一源文件中。通过
CXX_SCAN_FOR_MODULES
、CXX_SCAN_FOR_MODULES
或作为CXX_MODULES
文件集成员而被扫描 C++ 模块源的任何源文件将不会被合并到统一源文件中。有关详细信息,请参见cmake-cxxmodules(7)
。项目可以通过将其
SKIP_UNITY_BUILD_INCLUSION
源属性设置为 true 来阻止单个源文件被合并到统一源文件中。这比为整个目标禁用统一构建更能有效地防止特定文件出现问题。项目可以设置
UNITY_BUILD_UNIQUE_ID
以生成一个有效的 C 标识符,该标识符在统一构建中对于每个文件都是唯一的。这可用于避免统一构建中匿名命名空间的问题。可以使用
UNITY_BUILD_CODE_BEFORE_INCLUDE
和UNITY_BUILD_CODE_AFTER_INCLUDE
目标属性将代码注入到每个#include
语句之前和之后。通过
add_library()
、add_executable()
或target_sources()
等命令添加到目标的源文件顺序将在生成的统一源文件中保留。这可用于根据UNITY_BUILD_BATCH_SIZE
目标属性手动强制执行特定分组。