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
静态库被链接进去。
可执行文件¶
可执行文件是通过链接目标文件创建的二进制文件,其中一个包含程序入口点,例如 main
。
add_executable()
命令定义一个可执行目标。
add_executable(mytool mytool.cpp)
CMake 生成构建规则,将源文件编译成目标文件并链接成可执行文件。
可执行文件的链接依赖项可以使用 target_link_libraries()
命令指定。链接器从可执行文件自身源文件编译而来的目标文件开始,然后通过搜索链接库来解析剩余的符号依赖项。
诸如 add_custom_command()
等命令,它生成在构建时运行的规则,可以透明地使用 EXECUTABLE
目标作为 COMMAND
可执行文件。构建系统规则将确保在尝试运行命令之前构建可执行文件。
静态库¶
静态库是目标文件的归档。它们由归档器生成,而不是链接器。可执行文件、共享库 和 模块库 可以链接到静态库作为依赖项。链接器根据需要从静态库中选择目标文件子集,以解析符号并将其链接到使用它们的二进制文件中。每个链接到静态库的二进制文件都会获得自己的符号副本,并且静态库本身在运行时不需要。
当调用 add_library()
命令并带有 STATIC
库类型时,它定义一个静态库目标。
add_library(archive STATIC archive.cpp zip.cpp lzma.cpp)
或者,当 BUILD_SHARED_LIBS
变量为假时,不带类型。
add_library(archive archive.cpp zip.cpp lzma.cpp)
CMake 生成构建规则,将源文件编译成目标文件并将其归档到静态库中。
静态库的链接依赖项可以使用 target_link_libraries()
命令指定。由于静态库是归档文件而不是链接的二进制文件,因此其链接依赖项中的目标文件不包含在库本身中(除了指定为*直接*链接依赖项的对象库)。相反,CMake 记录静态库的链接依赖项,以便在链接使用它们的二进制文件时进行传递使用。
Apple Frameworks¶
共享库 和 静态库 可以通过 FRAMEWORK
目标属性标记,以创建 macOS 或 iOS Framework。带有 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
)
模块库¶
模块库是通过链接目标文件创建的二进制文件。与共享库不同,模块库不能被其他二进制文件作为依赖项链接——不要在target_link_libraries()
命令的右侧命名它们。相反,模块库是应用程序可以在运行时按需动态加载的插件,例如通过dlopen
。
当调用 add_library()
命令并带有 MODULE
库类型时,它定义一个模块库目标。
add_library(archivePlugin MODULE 7z.cpp)
CMake 生成构建规则,将源文件编译成目标文件并将其链接成模块库。
模块库的链接依赖项可以使用 target_link_libraries()
命令指定。链接器从模块库自身源文件编译而来的目标文件开始,然后通过搜索链接库来解析剩余的符号依赖项。
对象库¶
对象库是编译源文件而不进行任何归档或链接而创建的对象文件集合。这些对象文件可在链接可执行文件、共享库和模块库时使用,或在归档静态库时使用。
当调用 add_library()
命令并带有 OBJECT
库类型时,它定义一个对象库目标。
add_library(archiveObjs OBJECT archive.cpp zip.cpp lzma.cpp)
CMake 生成构建规则,将源文件编译成目标文件。
其他目标可以使用 生成器表达式
语法 $<TARGET_OBJECTS:name>
将对象文件指定为源输入。
add_library(archiveExtras STATIC $<TARGET_OBJECTS:archiveObjs> extras.cpp)
add_executable(test_exe $<TARGET_OBJECTS:archiveObjs> test.cpp)
使用目标文件及其自身源文件和命名对象库中的目标文件来链接(或归档)使用目标。
或者,可以将对象库指定为其他目标的链接依赖项。
add_library(archiveExtras STATIC extras.cpp)
target_link_libraries(archiveExtras PUBLIC archiveObjs)
add_executable(test_exe test.cpp)
target_link_libraries(test_exe archiveObjs)
使用目标文件及其自身源文件和通过 target_link_libraries()
指定为*直接*链接依赖项的对象库来链接(或归档)使用目标。请参阅链接对象库。
对象库不能用作 add_custom_command(TARGET)
命令签名的 TARGET
。但是,对象列表可以通过使用 $<TARGET_OBJECTS:objlib>
来用于 add_custom_command(OUTPUT)
或 file(GENERATE)
。
构建规范和使用要求¶
目标根据其自身的构建规范以及从其链接依赖项传播的使用要求进行构建。两者都可以使用目标特定的命令指定。
例如
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)
目标命令¶
目标特定命令填充二进制目标的构建规范以及二进制目标、接口库和导入目标的使用要求。
调用必须指定范围关键字,每个关键字都影响其后参数的可见性。这些范围是
这些命令是
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 中新增。
编译目标中源文件所需的
编译特性
列表。通常,这些特性确保目标的源文件使用足够的语言标准级别进行编译。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 中新增。
编译目标使用者中的源文件所需的
编译特性
列表。通常,这些特性确保在编译使用者时,目标头文件使用足够的语言标准级别进行处理。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 版本新增。
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
与 exe1
目标的 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:CMP0182>:CONSUMER_CMP0182_NEW>
)
add_executable(exe1 exe1.cpp)
target_link_libraries(exe1 lib1)
cmake_policy(SET CMP0182 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_CMP0182_NEW
编译,因为在创建shared_lib
目标时,策略CMP0182
是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
进行编译。导出命令生成IMPORTED
目标时,会省略INSTALL_INTERFACE
或BUILD_INTERFACE
,并去除*_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
)
相对路径相对于命令出现的源目录进行解释。在IMPORTED
目标的INTERFACE_INCLUDE_DIRECTORIES
中不允许使用相对路径。
在使用非平凡的生成器表达式的情况下,INSTALL_PREFIX
表达式可以在INSTALL_INTERFACE
表达式的参数中使用。它是一个替换标记,在被使用项目导入时扩展为安装前缀。
包含目录使用要求在构建树和安装树之间通常不同。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
附加到install(EXPORT)
生成的所有已安装IMPORTED
目标的INTERFACE_INCLUDE_DIRECTORIES
中。
当使用导入目标的INTERFACE_INCLUDE_DIRECTORIES
时,属性中的条目可以被视为系统包含目录。其效果取决于工具链,但一个常见的效果是忽略那些目录中找到的头文件的编译器警告。SYSTEM
已安装目标的属性决定了此行为(参见EXPORT_NO_SYSTEM
属性,了解如何修改目标的已安装值)。还可以通过设置使用方上的NO_SYSTEM_FROM_IMPORTED
目标属性来更改使用方如何解释所使用的导入目标的系统行为。
如果二进制目标传递地链接到 macOS FRAMEWORK
,则该框架的 Headers
目录也会被视为使用要求。这与将框架目录作为包含目录传递具有相同的效果。
链接库和生成器表达式¶
与构建规范类似,链接库
可以使用生成器表达式条件来指定。但是,由于使用要求的消费基于从链接依赖项的收集,因此还有一个额外的限制,即链接依赖项必须形成一个“有向无环图”。也就是说,如果链接到目标的依赖项取决于目标属性的值,则该目标属性不能依赖于链接的依赖项
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 平台上:
add_executable()
命令创建的可执行目标的导入库文件(例如.lib
),当其ENABLE_EXPORTS
目标属性已设置时。在 AIX 上:
add_executable()
命令创建的可执行目标的链接器导入文件(例如.imp
),当其ENABLE_EXPORTS
目标属性已设置时。在 macOS 上:
add_library()
命令使用SHARED
选项创建的共享库的链接器导入文件(例如.tbd
),并且当其ENABLE_EXPORTS
目标属性已设置时。
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()
无论使用何种生成器,都应使用生成器表达式
来正确处理特定于配置的逻辑。例如
# 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
,而且为 DEBUG
、debug
甚至 DeBuG
,都将评估为 1。因此,您可以在CMAKE_BUILD_TYPE
和CMAKE_CONFIGURATION_TYPES
中以任何大写和小写混合的方式指定配置类型,尽管有严格的约定(参见下一节)。如果您必须在字符串比较中测试该值,请务必先将该值转换为大写或小写,并相应地调整测试。
默认和自定义配置¶
默认情况下,CMake 定义了许多标准配置
调试
发布
发布带调试信息
最小尺寸发布
在多配置生成器中,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
。
LOCATION
也可以从IMPORTED目标读取,尽管很少有这样做的理由。add_custom_command()
等命令可以透明地使用IMPORTED
EXECUTABLE
目标作为COMMAND
可执行文件。
一个IMPORTED
目标的定义范围是它被定义的目录。它可以在子目录中访问和使用,但不能在父目录或兄弟目录中访问和使用。该范围类似于cmake变量的范围。
也可以定义一个GLOBAL
IMPORTED
目标,该目标在构建系统中全局可访问。
有关使用IMPORTED
目标创建包的更多信息,请参阅cmake-packages(7)
手册。
别名目标¶
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
库目标不编译源文件,也不在磁盘上生成库工件,因此它没有LOCATION
。
它可以指定使用要求,例如INTERFACE_INCLUDE_DIRECTORIES
、INTERFACE_COMPILE_DEFINITIONS
、INTERFACE_COMPILE_OPTIONS
、INTERFACE_LINK_LIBRARIES
、INTERFACE_SOURCES
和INTERFACE_POSITION_INDEPENDENT_CODE
。只有target_include_directories()
、target_compile_definitions()
、target_compile_options()
、target_sources()
和target_link_libraries()
命令的INTERFACE
模式可用于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 PUBLIC
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
。安装目的地自动成为包含目录,这是使用方的使用要求。