cmake-buildsystem(7)¶

简介 ¶

基于 CMake 的构建系统组织为一组高级逻辑目标。每个目标对应一个可执行文件或库，或者是一个包含自定义命令的自定义目标。构建系统中表达了目标之间的依赖关系，以确定构建顺序以及响应更改的重新生成规则。

二进制目标 ¶

使用 add_executable() 和 add_library() 命令定义可执行文件和库。生成的二进制文件具有针对目标平台的适当 PREFIX、SUFFIX 和扩展名。二进制目标之间的依赖关系使用 target_link_libraries() 命令表达。

add_library(archive archive.cpp zip.cpp lzma.cpp)
add_executable(zipapp zipapp.cpp)
target_link_libraries(zipapp archive)

archive 定义为一个 STATIC 库——一个包含从 archive.cpp、zip.cpp 和 lzma.cpp 编译的对象的归档文件。 zipapp 定义为通过编译和链接 zipapp.cpp 形成的可执行文件。链接 zipapp 可执行文件时，会链接 archive 静态库。

二进制可执行文件 ¶

add_executable() 命令定义一个可执行文件目标。

add_executable(mytool mytool.cpp)

诸如 add_custom_command() 之类的命令，它生成在构建时运行的规则，可以透明地使用 EXECUTABLE 目标作为 COMMAND 可执行文件。构建系统规则将确保在尝试运行命令之前构建可执行文件。

二进制库类型 ¶

普通库 ¶

默认情况下，add_library() 命令定义一个 STATIC 库，除非指定了类型。在使用命令时可以指定类型。

add_library(archive SHARED archive.cpp zip.cpp lzma.cpp)

add_library(archive STATIC archive.cpp zip.cpp lzma.cpp)

BUILD_SHARED_LIBS 变量可以启用，以更改 add_library() 的行为，使其默认构建共享库。

在整个构建系统定义的上下文中，特定库是 SHARED 还是 STATIC 在很大程度上无关紧要——无论库类型如何，命令、依赖项规范和其他 API 的工作方式都类似。MODULE 库类型与此不同，因为它通常不链接——它不用于 target_link_libraries() 命令的右侧。它是一种使用运行时技术加载为插件的类型。如果库不导出任何非托管符号（例如 Windows 资源 DLL、C++/CLI DLL），则需要该库不是 SHARED 库，因为 CMake 期望 SHARED 库至少导出一个符号。

add_library(archive MODULE 7z.cpp)

Apple 框架 ¶

可以使用 FRAMEWORK 目标属性标记 SHARED 库以创建 macOS 或 iOS 框架捆绑包。具有 FRAMEWORK 目标属性的库还应设置 FRAMEWORK_VERSION 目标属性。根据 macOS 约定，此属性通常设置为“A”的值。MACOSX_FRAMEWORK_IDENTIFIER 设置 CFBundleIdentifier 密钥，它唯一地标识捆绑包。

add_library(MyFramework SHARED MyFramework.cpp)
set_target_properties(MyFramework PROPERTIES
  FRAMEWORK TRUE
  FRAMEWORK_VERSION A # Version "A" is macOS convention
  MACOSX_FRAMEWORK_IDENTIFIER org.cmake.MyFramework
)

对象库 ¶

OBJECT 库类型定义了一个非归档的对象文件集合，这些文件是编译给定源文件的结果。对象文件集合可以通过使用语法 $<TARGET_OBJECTS:name> 作为其他目标的源输入。这是一个 generator expression，可用于为其他目标提供 OBJECT 库内容。

add_library(archive OBJECT archive.cpp zip.cpp lzma.cpp)

add_library(archiveExtras STATIC $<TARGET_OBJECTS:archive> extras.cpp)

add_executable(test_exe $<TARGET_OBJECTS:archive> test.cpp)

这些其他目标的链接（或归档）步骤将使用对象文件集合以及来自其自身源文件的文件。

或者，对象库可以链接到其他目标。

add_library(archive OBJECT archive.cpp zip.cpp lzma.cpp)

add_library(archiveExtras STATIC extras.cpp)
target_link_libraries(archiveExtras PUBLIC archive)

add_executable(test_exe test.cpp)
target_link_libraries(test_exe archive)

这些其他目标的链接（或归档）步骤将使用来自直接链接的OBJECT库的对象文件。此外，在编译这些其他目标中的源文件时，将遵守OBJECT库的使用需求。此外，这些使用需求将传递地传播到这些其他目标的依赖项。

对象库不能用作TARGET，在使用add_custom_command(TARGET) 命令签名时。但是，对象列表可以被add_custom_command(OUTPUT) 或file(GENERATE) 使用，方法是使用$<TARGET_OBJECTS:objlib>。

构建规范和使用需求 ¶

目标根据其自身的构建规范以及从其链接依赖项传播的使用需求进行构建。两者都可以使用目标特定的命令来指定。

例如

add_library(archive SHARED archive.cpp zip.cpp)

if (LZMA_FOUND)
  # Add a source implementing support for lzma.
  target_sources(archive PRIVATE lzma.cpp)

  # Compile the 'archive' library sources with '-DBUILDING_WITH_LZMA'.
  target_compile_definitions(archive PRIVATE BUILDING_WITH_LZMA)
endif()

target_compile_definitions(archive INTERFACE USING_ARCHIVE_LIB)

add_executable(consumer consumer.cpp)

# Link 'consumer' to 'archive'.  This also consumes its usage requirements,
# so 'consumer.cpp' is compiled with '-DUSING_ARCHIVE_LIB'.
target_link_libraries(consumer archive)

目标命令 ¶

目标特定的命令填充构建规范的二进制目标和使用需求的二进制目标、接口库和导入目标。

调用必须指定作用域关键字，每个关键字都会影响其后参数的可见性。作用域为

PUBLIC: 填充构建和使用目标的属性。
PRIVATE: 仅填充构建目标的属性。
INTERFACE: 仅填充使用目标的属性。

命令为

target_compile_definitions()

填充COMPILE_DEFINITIONS 构建规范和INTERFACE_COMPILE_DEFINITIONS 使用需求属性。

例如，调用

target_compile_definitions(archive
  PRIVATE   BUILDING_WITH_LZMA
  INTERFACE USING_ARCHIVE_LIB
)

将BUILDING_WITH_LZMA 附加到目标的COMPILE_DEFINITIONS 属性，并将USING_ARCHIVE_LIB 附加到目标的INTERFACE_COMPILE_DEFINITIONS 属性。

target_compile_options()

填充COMPILE_OPTIONS 构建规范和INTERFACE_COMPILE_OPTIONS 使用需求属性。

target_compile_features()

在版本 3.1 中添加。

填充COMPILE_FEATURES 构建规范和INTERFACE_COMPILE_FEATURES 使用需求属性。

target_include_directories()

填充INCLUDE_DIRECTORIES 构建规范和INTERFACE_INCLUDE_DIRECTORIES 使用需求属性。使用SYSTEM 选项，它还会填充INTERFACE_SYSTEM_INCLUDE_DIRECTORIES 使用需求。

为了方便起见，可以启用CMAKE_INCLUDE_CURRENT_DIR 变量，以便在所有目标上将源目录和相应的构建目录添加为INCLUDE_DIRECTORIES。类似地，可以启用CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE 变量，以便将它们添加为所有目标上的INTERFACE_INCLUDE_DIRECTORIES。

target_sources()

在版本 3.1 中添加。

填充SOURCES 构建规范和INTERFACE_SOURCES 使用需求属性。

它还支持指定文件集，它可以添加未在SOURCES 和INTERFACE_SOURCES 属性中列出的 C++ 模块源文件和头文件。文件集还可以使用包含头文件的包含目录填充INCLUDE_DIRECTORIES 构建规范和INTERFACE_INCLUDE_DIRECTORIES 使用需求属性。

target_precompile_headers()

在版本 3.16 中添加。

填充PRECOMPILE_HEADERS 构建规范和INTERFACE_PRECOMPILE_HEADERS 使用需求属性。

target_link_libraries()

填充LINK_LIBRARIES 构建规范和INTERFACE_LINK_LIBRARIES 使用需求属性。

这是链接依赖项及其使用需求传递传播以影响目标的编译和链接的主要机制。

target_link_directories()

在版本 3.13 中添加。

填充 LINK_DIRECTORIES 构建规范和 INTERFACE_LINK_DIRECTORIES 使用需求属性。

target_link_options()

在版本 3.13 中添加。

填充 LINK_OPTIONS 构建规范和 INTERFACE_LINK_OPTIONS 使用需求属性。

目标构建规范 ¶

目标的构建规范由目标属性表示。对于以下每个编译和链接属性，目标的编译和链接都受其自身值以及从链接依赖关系的传递闭包中收集的相应使用需求属性（以 INTERFACE_ 前缀命名）的影响。

目标编译属性 ¶

这些表示用于编译目标的构建规范。

COMPILE_DEFINITIONS

目标中编译源代码的编译定义列表。这些定义以 -D 标志（或等效标志）传递给编译器，顺序未指定。

DEFINE_SYMBOL 目标属性也用作编译定义，作为 SHARED 和 MODULE 库目标的特殊便利情况。

COMPILE_OPTIONS

目标中编译源代码的编译选项列表。这些选项按出现顺序作为标志传递给编译器。

编译选项会自动转义以适应 shell。

某些编译选项最好通过专用设置来指定，例如 POSITION_INDEPENDENT_CODE 目标属性。

COMPILE_FEATURES

在版本 3.1 中添加。

目标中编译源代码所需的 compile features 列表。通常，这些特性确保目标的源代码使用足够高的语言标准级别进行编译。

INCLUDE_DIRECTORIES

目标中编译源代码的包含目录列表。这些目录以 -I 或 -isystem 标志（或等效标志）传递给编译器，按出现顺序排列。

为方便起见，可以启用 CMAKE_INCLUDE_CURRENT_DIR 变量，以便在所有目标上将源代码目录和相应的构建目录添加为 INCLUDE_DIRECTORIES。

SOURCES

与目标关联的源文件列表。这包括通过 add_executable()、add_library() 或 add_custom_target() 命令创建目标时指定的源代码。它还包括 target_sources() 命令添加的源代码，但不包括文件集。

PRECOMPILE_HEADERS

在版本 3.16 中添加。

要预编译并在目标中编译源代码时包含的头文件列表。

AUTOMOC_MACRO_NAMES

3.10 版本中添加。

AUTOMOC 使用的宏名称列表，用于确定目标中的 C++ 源代码是否需要由 moc 处理。

AUTOUIC_OPTIONS

3.0 版本中添加。

AUTOUIC 调用 uic 时使用的选项列表。

目标链接属性 ¶

这些表示用于链接目标的构建规范。

LINK_LIBRARIES

如果目标是可执行文件、共享库或模块库，则用于链接目标的链接库列表。普通库的条目通过其链接构件的路径传递给链接器，或者使用 -l 标志或等效标志。对象库的条目通过其对象文件的路径传递给链接器。

此外，为了编译和链接目标本身，使用需求会从命名普通库、接口库、对象库和导入的目标的 LINK_LIBRARIES 条目中传播，并通过其 INTERFACE_LINK_LIBRARIES 属性的传递闭包收集。

LINK_DIRECTORIES

在版本 3.13 中添加。

如果目标是可执行文件、共享库或模块库，则用于链接目标的链接目录列表。这些目录使用 -L 标志（或等效标志）传递给链接器。

LINK_OPTIONS

在版本 3.13 中添加。

如果目标是可执行文件、共享库或模块库，则用于链接目标的链接选项列表。这些选项按出现顺序作为标志传递给链接器。

链接选项会自动转义以适应 shell。

LINK_DEPENDS

如果目标是可执行文件、共享库或模块库，则链接目标依赖的文件列表。例如，通过 LINK_OPTIONS 指定的链接器脚本可以列在此处，以便更改它们会导致重新链接二进制文件。

目标使用需求 ¶

目标的使用需求是传播到使用者（通过 target_link_libraries() 链接到目标）的设置，以便正确地编译和链接目标。它们由传递的编译和链接属性表示。

请注意，使用要求并非旨在作为一种方法来强制下游使用特定的COMPILE_OPTIONS、COMPILE_DEFINITIONS等，仅为方便起见。这些属性的内容必须是**要求**，而不仅仅是建议。

有关在创建用于重新分发的包时指定使用要求时必须采取的其他注意事项的讨论，请参阅创建可重定位包部分的cmake-packages(7)手册。

目标的使用要求可以传递传播到其依赖项。 target_link_libraries()命令具有PRIVATE、INTERFACE和PUBLIC关键字来控制传播。

add_library(archive archive.cpp)
target_compile_definitions(archive INTERFACE USING_ARCHIVE_LIB)

add_library(serialization serialization.cpp)
target_compile_definitions(serialization INTERFACE USING_SERIALIZATION_LIB)

add_library(archiveExtras extras.cpp)
target_link_libraries(archiveExtras PUBLIC archive)
target_link_libraries(archiveExtras PRIVATE serialization)
# archiveExtras is compiled with -DUSING_ARCHIVE_LIB
# and -DUSING_SERIALIZATION_LIB

add_executable(consumer consumer.cpp)
# consumer is compiled with -DUSING_ARCHIVE_LIB
target_link_libraries(consumer archiveExtras)

因为archive是archiveExtras的PUBLIC依赖项，所以它的使用要求也会传播到consumer。

因为serialization是archiveExtras的PRIVATE依赖项，所以它的使用要求不会传播到consumer。

通常，如果某个依赖项仅由库的实现使用，而不是在头文件中使用，则应使用target_link_libraries()的PRIVATE关键字指定该依赖项。如果某个依赖项还用于库的头文件（例如，用于类继承），则应将其指定为PUBLIC依赖项。不使用库的实现而仅由其头文件使用的依赖项应指定为INTERFACE依赖项。target_link_libraries()命令可以使用每个关键字的多个用法。

target_link_libraries(archiveExtras
  PUBLIC archive
  PRIVATE serialization
)

使用要求通过读取依赖项的目标属性的INTERFACE_变体并将值附加到操作数的非INTERFACE_变体来传播。例如，读取依赖项的INTERFACE_INCLUDE_DIRECTORIES并将其附加到操作数的INCLUDE_DIRECTORIES。在顺序相关且保持顺序的情况下，并且target_link_libraries()调用的结果顺序不允许正确编译时，可以使用适当的命令直接设置属性来更新顺序。

例如，如果目标的链接库必须按lib1 lib2 lib3的顺序指定，但包含目录必须按lib3 lib1 lib2的顺序指定

target_link_libraries(myExe lib1 lib2 lib3)
target_include_directories(myExe
  PRIVATE $<TARGET_PROPERTY:lib3,INTERFACE_INCLUDE_DIRECTORIES>)

请注意，在为将使用install(EXPORT)命令导出以进行安装的目标指定使用要求时，必须小心谨慎。有关更多信息，请参阅创建包。

传递编译属性 ¶

这些表示用于编译使用者使用要求。

INTERFACE_COMPILE_DEFINITIONS: 用于编译目标使用者中的源代码的编译定义列表。通常，这些由目标的头文件使用。
INTERFACE_COMPILE_OPTIONS: 用于编译目标使用者中的源代码的编译选项列表。
INTERFACE_COMPILE_FEATURES: 在版本 3.1 中添加。

用于编译目标使用者中的源代码所需的compile features列表。通常，这些确保在使用足够高的语言标准级别编译使用者时处理目标的头文件。
INTERFACE_INCLUDE_DIRECTORIES: 用于编译目标使用者中的源代码的包含目录列表。通常，这些是目标头文件的位置。
INTERFACE_SYSTEM_INCLUDE_DIRECTORIES: 目录列表，当指定为包含目录时（例如，由INCLUDE_DIRECTORIES或INTERFACE_INCLUDE_DIRECTORIES指定），在编译目标使用者中的源代码时应将其视为“系统”包含目录。
INTERFACE_SOURCES: 与目标使用者关联的源文件列表。
INTERFACE_PRECOMPILE_HEADERS: 在版本 3.16 中添加。

预编译并在编译目标使用者中的源代码时包含的头文件列表。
INTERFACE_AUTOMOC_MACRO_NAMES: 在版本 3.27 中添加。

由AUTOMOC使用的宏名称列表，用于确定目标使用者中的 C++ 源文件是否需要由moc处理。
INTERFACE_AUTOUIC_OPTIONS: 3.0 版本中添加。

当AUTOUIC为目标使用者调用uic时使用的选项列表。

传递链接属性 ¶

这些表示用于链接使用者使用要求。

INTERFACE_LINK_LIBRARIES

用于链接目标使用者的链接库列表，适用于可执行文件、共享库或模块库。这些是目标的传递依赖项。

此外，为了编译和链接目标的使用者，使用要求是从命名普通库、接口库、对象库和导入目标的INTERFACE_LINK_LIBRARIES条目的传递闭包中收集的。

INTERFACE_LINK_DIRECTORIES

在版本 3.13 中添加。

用于链接目标的使用者（如果是可执行文件、共享库或模块库）的链接目录列表。

INTERFACE_LINK_OPTIONS

在版本 3.13 中添加。

用于链接目标的使用者（如果是可执行文件、共享库或模块库）的链接选项列表。

INTERFACE_LINK_DEPENDS

在版本 3.13 中添加。

链接目标的使用者（如果是可执行文件、共享库或模块库）所依赖的文件列表。

自定义传递属性 ¶

在版本 3.30 中添加。

The TARGET_PROPERTY 生成器表达式会评估上述的构建规范和使用需求属性作为内置的传递属性。它还支持由目标及其链接依赖项上的 TRANSITIVE_COMPILE_PROPERTIES 和 TRANSITIVE_LINK_PROPERTIES 属性定义的自定义传递属性。

例如

add_library(example INTERFACE)
set_target_properties(example PROPERTIES
  TRANSITIVE_COMPILE_PROPERTIES "CUSTOM_C"
  TRANSITIVE_LINK_PROPERTIES    "CUSTOM_L"

  INTERFACE_CUSTOM_C "EXAMPLE_CUSTOM_C"
  INTERFACE_CUSTOM_L "EXAMPLE_CUSTOM_L"
  )

add_library(mylib STATIC mylib.c)
target_link_libraries(mylib PRIVATE example)
set_target_properties(mylib PROPERTIES
  CUSTOM_C           "MYLIB_PRIVATE_CUSTOM_C"
  CUSTOM_L           "MYLIB_PRIVATE_CUSTOM_L"
  INTERFACE_CUSTOM_C "MYLIB_IFACE_CUSTOM_C"
  INTERFACE_CUSTOM_L "MYLIB_IFACE_CUSTOM_L"
  )

add_executable(myexe myexe.c)
target_link_libraries(myexe PRIVATE mylib)
set_target_properties(myexe PROPERTIES
  CUSTOM_C "MYEXE_CUSTOM_C"
  CUSTOM_L "MYEXE_CUSTOM_L"
  )

add_custom_target(print ALL VERBATIM
  COMMAND ${CMAKE_COMMAND} -E echo
    # Prints "MYLIB_PRIVATE_CUSTOM_C;EXAMPLE_CUSTOM_C"
    "$<TARGET_PROPERTY:mylib,CUSTOM_C>"

    # Prints "MYLIB_PRIVATE_CUSTOM_L;EXAMPLE_CUSTOM_L"
    "$<TARGET_PROPERTY:mylib,CUSTOM_L>"

    # Prints "MYEXE_CUSTOM_C"
    "$<TARGET_PROPERTY:myexe,CUSTOM_C>"

    # Prints "MYEXE_CUSTOM_L;MYLIB_IFACE_CUSTOM_L;EXAMPLE_CUSTOM_L"
    "$<TARGET_PROPERTY:myexe,CUSTOM_L>"
  )

兼容接口属性 ¶

某些目标属性需要在目标和每个依赖项的接口之间兼容。例如，POSITION_INDEPENDENT_CODE 目标属性可以指定目标是否应作为位置无关代码编译的布尔值，这具有特定于平台的后果。目标还可以指定使用需求 INTERFACE_POSITION_INDEPENDENT_CODE 来传达使用者必须作为位置无关代码编译。

add_executable(exe1 exe1.cpp)
set_property(TARGET exe1 PROPERTY POSITION_INDEPENDENT_CODE ON)

add_library(lib1 SHARED lib1.cpp)
set_property(TARGET lib1 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)

add_executable(exe2 exe2.cpp)
target_link_libraries(exe2 lib1)

这里，exe1 和 exe2 都将作为位置无关代码编译。 lib1 也将作为位置无关代码编译，因为这是 SHARED 库的默认设置。如果依赖项具有冲突的、不兼容的要求，cmake(1) 会发出诊断信息。

add_library(lib1 SHARED lib1.cpp)
set_property(TARGET lib1 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)

add_library(lib2 SHARED lib2.cpp)
set_property(TARGET lib2 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE OFF)

add_executable(exe1 exe1.cpp)
target_link_libraries(exe1 lib1)
set_property(TARGET exe1 PROPERTY POSITION_INDEPENDENT_CODE OFF)

add_executable(exe2 exe2.cpp)
target_link_libraries(exe2 lib1 lib2)

lib1 的需求 INTERFACE_POSITION_INDEPENDENT_CODE 与 POSITION_INDEPENDENT_CODE 目标属性不“兼容”。库要求使用者构建为位置无关代码，而可执行文件指定不构建为位置无关代码，因此会发出诊断信息。

lib1 和 lib2 的需求不“兼容”。其中一个要求使用者构建为位置无关代码，而另一个要求使用者不构建为位置无关代码。因为 exe2 链接到两者并且它们存在冲突，所以会发出 CMake 错误消息。

CMake Error: The INTERFACE_POSITION_INDEPENDENT_CODE property of "lib2" does
not agree with the value of POSITION_INDEPENDENT_CODE already determined
for "exe2".

为了“兼容”，如果设置了 POSITION_INDEPENDENT_CODE 属性，则在布尔意义上，它必须与设置了该属性的所有传递指定的依赖项的 INTERFACE_POSITION_INDEPENDENT_CODE 属性相同。

可以通过在 COMPATIBLE_INTERFACE_BOOL 目标属性的内容中指定属性将“兼容接口需求”的此属性扩展到其他属性。每个指定的属性必须在使用目标和每个依赖项中带有 INTERFACE_ 前缀的对应属性之间兼容。

add_library(lib1Version2 SHARED lib1_v2.cpp)
set_property(TARGET lib1Version2 PROPERTY INTERFACE_CUSTOM_PROP ON)
set_property(TARGET lib1Version2 APPEND PROPERTY
  COMPATIBLE_INTERFACE_BOOL CUSTOM_PROP
)

add_library(lib1Version3 SHARED lib1_v3.cpp)
set_property(TARGET lib1Version3 PROPERTY INTERFACE_CUSTOM_PROP OFF)

add_executable(exe1 exe1.cpp)
target_link_libraries(exe1 lib1Version2) # CUSTOM_PROP will be ON

add_executable(exe2 exe2.cpp)
target_link_libraries(exe2 lib1Version2 lib1Version3) # Diagnostic

非布尔属性也可以参与“兼容接口”计算。在 COMPATIBLE_INTERFACE_STRING 属性中指定的属性必须未指定或与所有传递指定的依赖项中的相同字符串进行比较。这对于确保不会通过目标的传递需求将多个不兼容版本的库链接在一起非常有用。

add_library(lib1Version2 SHARED lib1_v2.cpp)
set_property(TARGET lib1Version2 PROPERTY INTERFACE_LIB_VERSION 2)
set_property(TARGET lib1Version2 APPEND PROPERTY
  COMPATIBLE_INTERFACE_STRING LIB_VERSION
)

add_library(lib1Version3 SHARED lib1_v3.cpp)
set_property(TARGET lib1Version3 PROPERTY INTERFACE_LIB_VERSION 3)

add_executable(exe1 exe1.cpp)
target_link_libraries(exe1 lib1Version2) # LIB_VERSION will be "2"

add_executable(exe2 exe2.cpp)
target_link_libraries(exe2 lib1Version2 lib1Version3) # Diagnostic

COMPATIBLE_INTERFACE_NUMBER_MAX 目标属性指定内容将以数字方式评估，并将计算所有指定内容中的最大数字。

add_library(lib1Version2 SHARED lib1_v2.cpp)
set_property(TARGET lib1Version2 PROPERTY INTERFACE_CONTAINER_SIZE_REQUIRED 200)
set_property(TARGET lib1Version2 APPEND PROPERTY
  COMPATIBLE_INTERFACE_NUMBER_MAX CONTAINER_SIZE_REQUIRED
)

add_library(lib1Version3 SHARED lib1_v3.cpp)
set_property(TARGET lib1Version3 PROPERTY INTERFACE_CONTAINER_SIZE_REQUIRED 1000)

add_executable(exe1 exe1.cpp)
# CONTAINER_SIZE_REQUIRED will be "200"
target_link_libraries(exe1 lib1Version2)

add_executable(exe2 exe2.cpp)
# CONTAINER_SIZE_REQUIRED will be "1000"
target_link_libraries(exe2 lib1Version2 lib1Version3)

类似地，COMPATIBLE_INTERFACE_NUMBER_MIN 可用于计算依赖项属性的数字最小值。

每个计算出的“兼容”属性值都可以在生成时使用生成器表达式在使用者中读取。

请注意，对于每个被依赖方，每个兼容接口属性中指定的属性集不得与任何其他属性中指定的属性集相交。

属性来源调试 ¶

由于构建规范可以由依赖项确定，因此创建目标的代码和负责设置构建规范的代码缺乏局部性可能会使代码更难推理。 cmake(1) 提供了一个调试工具来打印可能由依赖项确定的属性内容的来源。可以在 CMAKE_DEBUG_TARGET_PROPERTIES 变量文档中列出可以调试的属性。

set(CMAKE_DEBUG_TARGET_PROPERTIES
  INCLUDE_DIRECTORIES
  COMPILE_DEFINITIONS
  POSITION_INDEPENDENT_CODE
  CONTAINER_SIZE_REQUIRED
  LIB_VERSION
)
add_executable(exe1 exe1.cpp)

对于在 COMPATIBLE_INTERFACE_BOOL 或 COMPATIBLE_INTERFACE_STRING 中列出的属性，调试输出会显示哪个目标负责设置属性，以及哪些其他依赖项也定义了该属性。对于 COMPATIBLE_INTERFACE_NUMBER_MAX 和 COMPATIBLE_INTERFACE_NUMBER_MIN，调试输出会显示每个依赖项的属性值，以及该值是否确定新的极值。

使用生成器表达式的构建规范 ¶

构建规范可以使用 生成器表达式，其中包含可能是有条件的或仅在生成时才知道的内容。例如，可以使用 TARGET_PROPERTY 表达式读取计算出的属性的“兼容”值。

add_library(lib1Version2 SHARED lib1_v2.cpp)
set_property(TARGET lib1Version2 PROPERTY
  INTERFACE_CONTAINER_SIZE_REQUIRED 200)
set_property(TARGET lib1Version2 APPEND PROPERTY
  COMPATIBLE_INTERFACE_NUMBER_MAX CONTAINER_SIZE_REQUIRED
)

add_executable(exe1 exe1.cpp)
target_link_libraries(exe1 lib1Version2)
target_compile_definitions(exe1 PRIVATE
    CONTAINER_SIZE=$<TARGET_PROPERTY:CONTAINER_SIZE_REQUIRED>
)

在这种情况下，exe1 源文件将使用 -DCONTAINER_SIZE=200 进行编译。

一元 TARGET_PROPERTY 生成器表达式和 TARGET_POLICY 生成器表达式使用使用目标上下文进行评估。这意味着使用需求规范可能根据使用者以不同的方式进行评估。

add_library(lib1 lib1.cpp)
target_compile_definitions(lib1 INTERFACE
  $<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,EXECUTABLE>:LIB1_WITH_EXE>
  $<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,SHARED_LIBRARY>:LIB1_WITH_SHARED_LIB>
  $<$<TARGET_POLICY:CMP0041>:CONSUMER_CMP0041_NEW>
)

add_executable(exe1 exe1.cpp)
target_link_libraries(exe1 lib1)

cmake_policy(SET CMP0041 NEW)

add_library(shared_lib shared_lib.cpp)
target_link_libraries(shared_lib lib1)

exe1 可执行文件将使用 -DLIB1_WITH_EXE 进行编译，而 shared_lib 共享库将使用 -DLIB1_WITH_SHARED_LIB 和 -DCONSUMER_CMP0041_NEW 进行编译，因为在创建 shared_lib 目标时，策略 CMP0041 为 NEW。

BUILD_INTERFACE 表达式包含仅在从同一构建系统中的目标使用时，或在使用 export() 命令导出到构建目录的目标中使用时才使用的需求。 INSTALL_INTERFACE 表达式包含仅在从已安装并使用 install(EXPORT) 命令导出的目标中使用时才使用的需求。

add_library(ClimbingStats climbingstats.cpp)
target_compile_definitions(ClimbingStats INTERFACE
  $<BUILD_INTERFACE:ClimbingStats_FROM_BUILD_LOCATION>
  $<INSTALL_INTERFACE:ClimbingStats_FROM_INSTALLED_LOCATION>
)
install(TARGETS ClimbingStats EXPORT libExport ${InstallArgs})
install(EXPORT libExport NAMESPACE Upstream::
        DESTINATION lib/cmake/ClimbingStats)
export(EXPORT libExport NAMESPACE Upstream::)

add_executable(exe1 exe1.cpp)
target_link_libraries(exe1 ClimbingStats)

在这种情况下，exe1 可执行文件将使用 -DClimbingStats_FROM_BUILD_LOCATION 进行编译。导出命令生成具有 INSTALL_INTERFACE 或 BUILD_INTERFACE 省略的 IMPORTED 目标，并剥离 *_INTERFACE 标记。使用 ClimbingStats 包的单独项目将包含

find_package(ClimbingStats REQUIRED)

add_executable(Downstream main.cpp)
target_link_libraries(Downstream Upstream::ClimbingStats)

根据 ClimbingStats 包是从构建位置还是安装位置使用，Downstream 目标将使用 -DClimbingStats_FROM_BUILD_LOCATION 或 -DClimbingStats_FROM_INSTALL_LOCATION 进行编译。有关包和导出的更多信息，请参阅 cmake-packages(7) 手册。

包含目录和使用需求 ¶

当包含目录作为使用需求指定以及与生成器表达式一起使用时，需要一些特殊考虑。 target_include_directories() 命令接受相对和绝对包含目录。

add_library(lib1 lib1.cpp)
target_include_directories(lib1 PRIVATE
  /absolute/path
  relative/path
)

相对路径相对于命令出现的源目录进行解释。在 INTERFACE_INCLUDE_DIRECTORIES 的 IMPORTED 目标中不允许使用相对路径。

在使用非平凡生成器表达式的情况下，可以在 INSTALL_INTERFACE 表达式的参数内使用 INSTALL_PREFIX 表达式。它是一个替换标记，在使用目标项目导入时扩展到安装前缀。

包含目录的使用需求通常在构建树和安装树之间有所不同。 BUILD_INTERFACE 和 INSTALL_INTERFACE 生成器表达式可用于根据使用位置描述单独的使用需求。相对路径在 INSTALL_INTERFACE 表达式中允许，并相对于安装前缀进行解释。例如

add_library(ClimbingStats climbingstats.cpp)
target_include_directories(ClimbingStats INTERFACE
  $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/generated>
  $<INSTALL_INTERFACE:/absolute/path>
  $<INSTALL_INTERFACE:relative/path>
  $<INSTALL_INTERFACE:$<INSTALL_PREFIX>/$<CONFIG>/generated>
)

提供了两个与包含目录使用需求相关的便捷 API。可以启用 CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE 变量，其效果等同于

set_property(TARGET tgt APPEND PROPERTY INTERFACE_INCLUDE_DIRECTORIES
  $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR};${CMAKE_CURRENT_BINARY_DIR}>
)

每个受影响的目标。已安装目标的便捷方式是使用 install(TARGETS) 命令的 INCLUDES DESTINATION 组件。

install(TARGETS foo bar bat EXPORT tgts ${dest_args}
  INCLUDES DESTINATION include
)
install(EXPORT tgts ${other_args})
install(FILES ${headers} DESTINATION include)

这等效于将 ${CMAKE_INSTALL_PREFIX}/include 附加到每个已安装 IMPORTED 目标的 INTERFACE_INCLUDE_DIRECTORIES（当由 install(EXPORT) 生成时）。

当使用导入目标的 INTERFACE_INCLUDE_DIRECTORIES 时，属性中的条目可能会被视为系统包含目录。其效果取决于工具链，但一个常见的效果是省略对这些目录中找到的头文件的编译器警告。已安装目标的 SYSTEM 属性决定此行为（有关如何修改目标的已安装值的详细信息，请参阅 EXPORT_NO_SYSTEM 属性）。还可以通过在使用者上设置 NO_SYSTEM_FROM_IMPORTED 目标属性来更改使用者如何解释使用导入目标的系统行为。

如果二进制目标传递链接到 macOS FRAMEWORK，则框架的 Headers 目录也视为使用需求。这与将框架目录作为包含目录传递具有相同的效果。

链接库和生成器表达式 ¶

与构建规范类似，link libraries 可以使用生成器表达式条件进行指定。但是，由于使用需求的消费基于从链接依赖项中收集，因此存在一个额外的限制，即链接依赖项必须形成“有向无环图”。也就是说，如果链接到目标依赖于目标属性的值，则该目标属性不能依赖于链接的依赖项。

add_library(lib1 lib1.cpp)
add_library(lib2 lib2.cpp)
target_link_libraries(lib1 PUBLIC
  $<$<TARGET_PROPERTY:POSITION_INDEPENDENT_CODE>:lib2>
)
add_library(lib3 lib3.cpp)
set_property(TARGET lib3 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)

add_executable(exe1 exe1.cpp)
target_link_libraries(exe1 lib1 lib3)

由于 exe1 目标的 POSITION_INDEPENDENT_CODE 属性的值依赖于链接的库（lib3），并且链接 exe1 的边由相同的 POSITION_INDEPENDENT_CODE 属性确定，因此上面的依赖关系图包含一个循环。 cmake(1) 会发出错误消息。

输出工件 ¶

由 add_library() 和 add_executable() 命令创建的构建系统目标会创建规则来生成二进制输出。二进制文件的精确输出位置只能在生成时确定，因为它可能取决于构建配置、链接依赖项的链接语言等。TARGET_FILE、TARGET_LINKER_FILE 和相关的表达式可用于访问生成的二进制文件的文件名和位置。但是，这些表达式不适用于 OBJECT 库，因为此类库没有生成与这些表达式相关的单个文件。

目标可能构建三种输出工件，如下节所述。它们的分类在 DLL 平台和非 DLL 平台之间有所不同。所有基于 Windows 的系统（包括 Cygwin）都是 DLL 平台。

运行时输出工件 ¶

构建系统目标的运行时输出工件可能是

由 add_executable() 命令创建的可执行目标的可执行文件（例如 .exe）。
在 DLL 平台上：由 add_library() 命令使用 SHARED 选项创建的共享库目标的可执行文件（例如 .dll）。

可以使用 RUNTIME_OUTPUT_DIRECTORY 和 RUNTIME_OUTPUT_NAME 目标属性来控制构建树中运行时输出工件的位置和名称。

库输出工件 ¶

构建系统目标的库输出工件可能是

由 add_library() 命令使用 MODULE 选项创建的模块库目标的可加载模块文件（例如 .dll 或 .so）。
在非 DLL 平台上：由 add_library() 命令使用 SHARED 选项创建的共享库目标的共享库文件（例如 .so 或 .dylib）。

可以使用 LIBRARY_OUTPUT_DIRECTORY 和 LIBRARY_OUTPUT_NAME 目标属性来控制构建树中库输出工件的位置和名称。

归档输出工件 ¶

构建系统目标的归档输出工件可能是

由 add_library() 命令使用 STATIC 选项创建的静态库目标的静态库文件（例如 .lib 或 .a）。
在 DLL 平台上：由 add_library() 命令使用 SHARED 选项创建的共享库目标的导入库文件（例如 .lib）。仅当库导出至少一个非托管符号时，才能保证此文件存在。
在 DLL 平台上：当其 ENABLE_EXPORTS 目标属性设置为时，由 add_executable() 命令创建的可执行目标的导入库文件（例如 .lib）。
在 AIX 上：当其 ENABLE_EXPORTS 目标属性设置为时，由 add_executable() 命令创建的可执行目标的链接器导入文件（例如 .imp）。
在 macOS 上：当其 ENABLE_EXPORTS 目标属性设置为时，由 add_library() 命令使用 SHARED 选项创建的共享库目标的链接器导入文件（例如 .tbd）。

可以使用 ARCHIVE_OUTPUT_DIRECTORY 和 ARCHIVE_OUTPUT_NAME 目标属性来控制构建树中归档输出工件的位置和名称。

目录范围命令 ¶

target_include_directories()、target_compile_definitions() 和 target_compile_options() 命令一次只对一个目标有效。add_compile_definitions()、add_compile_options() 和 include_directories() 命令具有类似的功能，但为了方便起见，它们在目录范围内而不是目标范围内操作。

构建配置 ¶

配置确定特定类型构建的规范，例如 Release 或 Debug。其指定方式取决于所使用的 生成器 类型。对于单一配置生成器（如 Makefile 生成器和 Ninja），配置是在配置时通过 CMAKE_BUILD_TYPE 变量指定的。对于多配置生成器（如 Visual Studio、Xcode 和 Ninja Multi-Config），配置是在构建时由用户选择的，并且 CMAKE_BUILD_TYPE 将被忽略。在多配置情况下，可用配置的集合是在配置时通过 CMAKE_CONFIGURATION_TYPES 变量指定的，但实际使用的配置在构建阶段之前是无法知道的。这种差异经常被误解，导致出现如下所示的有问题的代码

# WARNING: This is wrong for multi-config generators because they don't use
#          and typically don't even set CMAKE_BUILD_TYPE
string(TOLOWER ${CMAKE_BUILD_TYPE} build_type)
if (build_type STREQUAL debug)
  target_compile_definitions(exe1 PRIVATE DEBUG_BUILD)
endif()

Generator expressions 应该用于处理特定于配置的逻辑，而不管使用的生成器是什么。例如

# Works correctly for both single and multi-config generators
target_compile_definitions(exe1 PRIVATE
  $<$<CONFIG:Debug>:DEBUG_BUILD>
)

在存在 IMPORTED 目标的情况下，MAP_IMPORTED_CONFIG_DEBUG 的内容也会被上述 $<CONFIG:Debug> 表达式考虑在内。

大小写敏感性 ¶

CMAKE_BUILD_TYPE 和 CMAKE_CONFIGURATION_TYPES 与其他变量类似，对其值进行的任何字符串比较都将区分大小写。 $<CONFIG> 生成器表达式也会保留用户设置或 CMake 默认设置的配置的大小写。例如

# NOTE: Don't use these patterns, they are for illustration purposes only.

set(CMAKE_BUILD_TYPE Debug)
if(CMAKE_BUILD_TYPE STREQUAL DEBUG)
  # ... will never get here, "Debug" != "DEBUG"
endif()
add_custom_target(print_config ALL
  # Prints "Config is Debug" in this single-config case
  COMMAND ${CMAKE_COMMAND} -E echo "Config is $<CONFIG>"
  VERBATIM
)

set(CMAKE_CONFIGURATION_TYPES Debug Release)
if(DEBUG IN_LIST CMAKE_CONFIGURATION_TYPES)
  # ... will never get here, "Debug" != "DEBUG"
endif()

相反，CMake 在内部使用配置修改行为的地方，会不区分大小写地对待配置类型。例如，$<CONFIG:Debug> 生成器表达式不仅会对 Debug 配置计算为 1，还会对 DEBUG、debug 甚至 DeBuG 计算为 1。因此，您可以在 CMAKE_BUILD_TYPE 和 CMAKE_CONFIGURATION_TYPES 中以任何大小写混合的方式指定配置类型，尽管存在一些强约定（请参阅下一节）。如果必须在字符串比较中测试该值，请始终先将该值转换为大写或小写，并相应地调整测试。

默认和自定义配置 ¶

默认情况下，CMake 定义了许多标准配置

Debug
Release
RelWithDebInfo
MinSizeRel

在多配置生成器中，CMAKE_CONFIGURATION_TYPES 变量将默认填充上述列表（可能是其中的一部分），除非项目或用户覆盖了它。实际使用的配置由用户在构建时选择。

对于单配置生成器，配置是使用 CMAKE_BUILD_TYPE 变量在配置时指定的，并且在构建时无法更改。默认值通常不是上述标准配置中的任何一个，而是空字符串。一个常见的误解是，这与 Debug 相同，但事实并非如此。用户应该始终明确指定构建类型以避免此常见问题。

上述标准配置类型在大多数平台上提供了合理的行为，但可以扩展以提供其他类型。每个配置都为正在使用的语言定义了一组编译器和链接器标志变量。这些变量遵循约定 CMAKE_<LANG>_FLAGS_<CONFIG>，其中 <CONFIG> 始终是配置名称的大写形式。在定义自定义配置类型时，请确保这些变量设置正确，通常作为缓存变量。

伪目标 ¶

某些目标类型不表示构建系统的输出，而只表示输入，例如外部依赖项、别名或其他非构建工件。伪目标在生成的构建系统中没有表示。

导入目标 ¶

一个 IMPORTED 目标表示一个预先存在的依赖项。通常，此类目标由上游包定义，应被视为不可变的。声明 IMPORTED 目标后，可以使用自定义命令（如 target_compile_definitions()、target_include_directories()、target_compile_options() 或 target_link_libraries()）调整其目标属性，就像使用任何其他常规目标一样。

IMPORTED 目标可能具有与二进制目标相同的用法要求属性，例如 INTERFACE_INCLUDE_DIRECTORIES、INTERFACE_COMPILE_DEFINITIONS、INTERFACE_COMPILE_OPTIONS、INTERFACE_LINK_LIBRARIES 和 INTERFACE_POSITION_INDEPENDENT_CODE。

也可以从 IMPORTED 目标读取 LOCATION，尽管很少有理由这样做。命令（如 add_custom_command()）可以透明地使用 IMPORTED EXECUTABLE 目标作为 COMMAND 可执行文件。

IMPORTED 目标定义的作用域是其定义所在的目录。可以从子目录访问和使用它，但不能从父目录或同级目录访问和使用它。作用域类似于 cmake 变量的作用域。

还可以定义一个 GLOBAL IMPORTED 目标，该目标在构建系统中全局可用。

有关使用 IMPORTED 目标创建包的更多信息，请参阅 cmake-packages(7) 手册。

别名目标 (Alias Targets)¶

一个 ALIAS 目标是一个名称，在只读上下文中可以与二进制目标名称互换使用。 ALIAS 目标的一个主要用例是例如库附带的示例或单元测试可执行文件，它们可能是构建系统的一部分，也可能根据用户配置单独构建。

add_library(lib1 lib1.cpp)
install(TARGETS lib1 EXPORT lib1Export ${dest_args})
install(EXPORT lib1Export NAMESPACE Upstream:: ${other_args})

add_library(Upstream::lib1 ALIAS lib1)

在另一个目录中，我们可以无条件地链接到 Upstream::lib1 目标，它可能是来自包的 IMPORTED 目标，或者如果作为同一个构建系统的一部分构建，则为 ALIAS 目标。

if (NOT TARGET Upstream::lib1)
  find_package(lib1 REQUIRED)
endif()
add_executable(exe1 exe1.cpp)
target_link_libraries(exe1 Upstream::lib1)

ALIAS 目标不可变、不可安装或不可导出。它们完全属于构建系统描述的本地范围。可以通过读取其 ALIASED_TARGET 属性来测试一个名称是否为 ALIAS 名称。

get_target_property(_aliased Upstream::lib1 ALIASED_TARGET)
if(_aliased)
  message(STATUS "The name Upstream::lib1 is an ALIAS for ${_aliased}.")
endif()

接口库 (Interface Libraries)¶

一个 INTERFACE 库目标不编译源代码，也不在磁盘上生成库工件，因此它没有 LOCATION。

它可以指定使用需求，例如 INTERFACE_INCLUDE_DIRECTORIES、INTERFACE_COMPILE_DEFINITIONS、INTERFACE_COMPILE_OPTIONS、INTERFACE_LINK_LIBRARIES、INTERFACE_SOURCES 和 INTERFACE_POSITION_INDEPENDENT_CODE。只有 INTERFACE 模式下的 target_include_directories()、target_compile_definitions()、target_compile_options()、target_sources() 和 target_link_libraries() 命令可以与 INTERFACE 库一起使用。

从 CMake 3.19 开始，INTERFACE 库目标可以选择包含源文件。包含源文件的接口库将在生成的构建系统中作为构建目标包含在内。它不编译源代码，但可能包含自定义命令来生成其他源代码。此外，IDE 将源文件显示为目标的一部分，以便交互式读取和编辑。

INTERFACE 库的主要用例是仅包含头文件的库。从 CMake 3.23 开始，可以通过使用 target_sources() 命令将它们添加到头文件集中，从而将头文件与库关联起来。

add_library(Eigen INTERFACE)

target_sources(Eigen PUBLIC
  FILE_SET HEADERS
    BASE_DIRS src
    FILES src/eigen.h src/vector.h src/matrix.h
)

add_executable(exe1 exe1.cpp)
target_link_libraries(exe1 Eigen)

当我们在此处指定 FILE_SET 时，我们定义的 BASE_DIRS 会自动成为目标 Eigen 的使用需求中的包含目录。目标的使用需求会被使用并在编译时使用，但对链接没有影响。

另一个用例是为使用需求采用完全以目标为中心的设计。

add_library(pic_on INTERFACE)
set_property(TARGET pic_on PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
add_library(pic_off INTERFACE)
set_property(TARGET pic_off PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE OFF)

add_library(enable_rtti INTERFACE)
target_compile_options(enable_rtti INTERFACE
  $<$<OR:$<COMPILER_ID:GNU>,$<COMPILER_ID:Clang>>:-rtti>
)

add_executable(exe1 exe1.cpp)
target_link_libraries(exe1 pic_on enable_rtti)

这样，exe1 的构建规范完全表示为链接的目标，编译器特定标志的复杂性封装在 INTERFACE 库目标中。

INTERFACE 库可以安装和导出。我们可以安装默认的头文件集以及目标。

add_library(Eigen INTERFACE)

target_sources(Eigen INTERFACE
  FILE_SET HEADERS
    BASE_DIRS src
    FILES src/eigen.h src/vector.h src/matrix.h
)

install(TARGETS Eigen EXPORT eigenExport
  FILE_SET HEADERS DESTINATION include/Eigen)
install(EXPORT eigenExport NAMESPACE Upstream::
  DESTINATION lib/cmake/Eigen
)

在这里，头文件集中定义的头文件被安装到 include/Eigen。安装目标会自动成为使用者使用需求的包含目录。

cmake-buildsystem(7)¶

简介 ¶

二进制目标 ¶

二进制可执行文件 ¶

二进制库类型 ¶

普通库 ¶

Apple 框架 ¶

对象库 ¶

构建规范和使用需求 ¶

目标命令 ¶

目标构建规范 ¶

目标编译属性 ¶

目标链接属性 ¶

目标使用需求 ¶

传递编译属性 ¶

传递链接属性 ¶

自定义传递属性 ¶

兼容接口属性 ¶

属性来源调试 ¶

使用生成器表达式的构建规范 ¶

包含目录和使用需求 ¶

链接库和生成器表达式 ¶

输出工件 ¶

运行时输出工件 ¶

库输出工件 ¶

归档输出工件 ¶

目录范围命令 ¶

构建配置 ¶

大小写敏感性 ¶

默认和自定义配置 ¶

伪目标 ¶

导入目标 ¶

别名目标 (Alias Targets)¶

接口库 (Interface Libraries)¶

目录

上一主题

下一主题

本页