cmake-建置系統(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 靜態庫。
目標名稱¶
Targets are addressed by name throughout the buildsystem. A target name
must be non-empty and contain only ASCII letters, digits, _, ., +,
and -. As a special case, ALIAS and IMPORTED
targets may also contain :. By convention, a double colon (::) is used
as a namespace separator, such as Upstream::lib1, to distinguish
ALIAS and IMPORTED targets from targets of other types, and to reduce
the likelihood of naming collisions. See the cmake-packages(7)
manual for more details.
Target names must be globally unique. Non-GLOBAL IMPORTED
targets are visible only in the directory that defines them and their
subdirectories.
CMake reserves some names for special targets created by the build tools and project-wide convenience targets.
The names
all,ALL_BUILD,help,install,INSTALL,preinstall,clean,edit_cache,rebuild_cache, andZERO_CHECKare always reserved.Some modules reserve additional names: e.g.,
testwhenCTestis enabled, andpackagewhenCPackis enabled.Generators may also create their own convenience targets, such as
install/parallelwith the Ninja 生成器. See thecmake-generators(7)manual for the target names documented by each generator.
Some convenience targets derive their names from other names in the project:
The
test_prep/<name>targets use test names, which have their own representability rules beyond those above. The Makefile 生成器 do not allow:. See also Test Preparation Targets.The
install_prep/<component>targets use install component names. A component name may contain the characters allowed in target names above, plus:and/. The Makefile 生成器 do not allow:. See also 安裝準備目標.
可執行文件¶
可執行檔案是由將物件檔連結起來所建立的二進位檔案,其中一個包含程式進入點,例如:main。
add_executable() 命令定義了一個可執行目標:
add_executable(mytool mytool.cpp)
CMake生成構建規則,以將源文件編譯成對象文件並鏈接為一個可執行文件。
可執行文件的鏈接依賴可以使用:command:`target_link_libraries`命令指定。鏈接器從可執行文件自己的源文件編譯的對象文件開始,然後通過搜索鏈接庫來解決剩餘的符號依賴。
像 add_custom_command() 這樣的命令會生成在構建時運行的規則,可以透明地使用 EXECUTABLE 目標作為 COMMAND 可執行文件。構建系統規則將確保在嘗試運行命令之前構建可執行文件。
靜態程式庫¶
靜態庫是對象文件的檔案。它們由歸檔器而不是鏈接器生成。 可執行文件,`共享庫`_和 `模塊庫`_可以將靜態庫作為依賴項鏈接。鏈接器會根據需要從靜態庫中選擇對象文件的子集以解析符號並將它們鏈接到消費者二進制文件中。每個鏈接到靜態庫的二進制文件都會獲得其符號的副本,在運行時不需要靜態庫本身。
當以 STATIC 庫類型調用時,add_library() 命令定義了一個靜態庫目標:
add_library(archive STATIC archive.cpp zip.cpp lzma.cpp)
或者,當 BUILD_SHARED_LIBS 變量為false時,無任何類型:
add_library(archive archive.cpp zip.cpp lzma.cpp)
CMake生成構建規則以將源文件編譯為對象文件並將其存檔到一個靜態庫中。
靜態庫的鏈接依賴可以使用:command:target_link_libraries`命令指定。由於靜態庫是檔案而不是鏈接的二進制文件,其鏈接依賴的對象文件不包含在它們自己中(除了指定為*直接*鏈接依賴的 `對象庫)。相反,CMake記錄靜態庫的鏈接依賴,以供連接消費者二進制時的傳遞使用。
Apple 框架¶
共享庫`_和 `靜態庫`_可以使用 :prop_tgt:`FRAMEWORK 目標屬性標記,以創建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
)
模組程式庫¶
模塊庫是通過鏈接對象文件創建的二進制文件。 與 共享庫`_不同,模塊庫可能不會被其他二進制文件作為依賴項鏈接——不要在:command:`target_link_libraries`命令的右側命名它們。相反,模塊庫是應用程序可以在運行時按需動態加載的插件,例如,通過``dlopen`。
當以 MODULE 庫類型調用時,add_library() 命令定義了一個模塊庫目標:
add_library(archivePlugin MODULE 7z.cpp)
CMake生成構建規則來將源文件編譯成對象文件並將其鏈接成模塊庫。
模塊庫的鏈接依賴可以使用:command:`target_link_libraries`命令指定。鏈接器從模塊庫自己的源文件編譯的對象文件開始,然後通過搜索鏈接庫解決剩餘的符號依賴。
物件程式庫¶
對象庫是源文件編譯而成的對象文件集合,不做任何歸檔或鏈接。這些對象文件可用於鏈接 可執行文件、 共享庫 和 模塊庫,或在歸檔 靜態庫 時使用。
當以 OBJECT 庫類型調用時,add_library() 命令定義了一個對象庫目標:
add_library(archiveObjs OBJECT archive.cpp zip.cpp lzma.cpp)
CMake生成構建規則以將源文件編譯為對象文件。
其他目標可以使用 generator expression 語法 $<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)
消费目标通过其自身源文件和由:command:target_link_libraries`指定作为*直接*链接依赖的对象库中的对象文件进行链接(或存档)。 见:ref:`链接对象库。
對象庫不能作為 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)
目標命令¶
目标特定的命令填充了`二进制目标 <Binary Targets>`_的`构建规范 <构建规范>`_以及`二进制目标 <Binary Targets>`_、接口库 <接口库_>`_和`已引入目标 <已引入目标_>`_的`使用要求。
調用必須指定作用域關鍵字,每個關鍵字影響後續引數的可見性。 作用域為:
命令有:
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使用需求屬性。
File Sets¶
在 3.23 版被加入.
File sets associate files with a target as structured groups. A target has zero or more named file sets. Each file set has:
a name
a type
a scope of
INTERFACE,PUBLIC, orPRIVATEone or more base directories
files within those directories
File sets are added to targets with target_sources() using the
FILE_SET signature. See target_sources() for argument syntax and
validation details.
在 4.4 版的變更: A file may belong to at most one non-HEADERS file set in a target.
See policy CMP0211.
Acceptable file set types are:
HEADERS
Sources intended to be used via a language's
#includemechanism.
SOURCES在 4.4 版被加入.
Specifies sources to use when building a target and/or its dependents. With the scope
PRIVATEandPUBLIC, items populate theSOURCESproperty of the file set, which is used when building the target itself. With the scopePUBLICandINTERFACE, items populate theINTERFACE_SOURCESproperty of the file set, which is used when building dependents. Sources specified byINTERFACE_SOURCESpropagate transitively to dependents.SYCL在 4.5 版被加入.
An alias for
SOURCESthat initializes the file set'sLANGUAGEproperty toSYCL. Files in the set are compiled as SYCL sources even when their file name extension would normally select another language. The source file'sLANGUAGEproperty is not changed.The file set is recorded as type
SOURCESand otherwise has the same behavior and target properties as that type.This alias is experimental and gated by
CMAKE_EXPERIMENTAL_SYCL.SYCL_HEADERS在 4.5 版被加入.
An alias for
HEADERSthat initializes the file set'sLANGUAGEproperty toSYCL. A target compiles all of its C++ sources as SYCL when this file set is visible to its own build, or is reachable through the interface of a linked target. This behavior propagates transitively through linked target interfaces.The file set is recorded as type
HEADERSand otherwise has the same behavior and target properties as that type. The header files themselves are not compiled.This alias is experimental and gated by
CMAKE_EXPERIMENTAL_SYCL.CXX_MODULES在 3.28 版被加入.
Sources which contain C++ interface module or partition units (i.e., those using the
exportkeyword). This file set type may not have anINTERFACEscope except onIMPORTEDtargets.<rule>在 4.5 版被加入.
Specifies sources which will be processed by the custom rule defined by the
add_custom_rule()command.
For HEADERS, SOURCES, and CXX_MODULES types, the optional default
file sets are named after their type.
For <rule> types, the target may be a custom target.
For HEADERS and CXX_MODULES types, the target may not be a
FRAMEWORK target.
Files in a PRIVATE or PUBLIC file set are marked as source files for
IDE integration. Additionally, files in HEADERS file sets have their
HEADER_FILE_ONLY property set to TRUE.
Files in an INTERFACE or PUBLIC file set can be installed by
install(TARGETS) and exported by install(EXPORT) and
export().
The following target properties are set by file sets and should not generally be manipulated directly:
For file sets of type HEADERS:
For file sets of type SOURCES:
For file sets of type CXX_MODULES:
Target properties related to include directories are also modified by file sets as follows:
If the type is
HEADERS, and the scope of the file set isPRIVATEorPUBLIC, allBASE_DIRSof the file set are wrapped in$<BUILD_INTERFACE>and appended to this property.
If the type is
HEADERS, and the scope of the file set isINTERFACEorPUBLIC, allBASE_DIRSof the file set are wrapped in$<BUILD_INTERFACE>and appended to this property.
File sets do not populate the SOURCES or
INTERFACE_SOURCES target properties. They are represented by
their own file set and type-specific properties.
目標建置規格¶
`二进制目标 <Binary Targets>`_的构建规范通过目标属性进行表示。对于以下`编译 <项目编译属性>`_和`链接 <链接属性>`_属性,目标的编译和链接受其自身值以及从链接依赖的传递闭包收集到的以``INTERFACE_``为前缀的`使用需要 <项目使用需要>`_属性的影响。
目標編譯屬性¶
這些表示用於編譯目標的 構建規範。
COMPILE_DEFINITIONS用於編譯目標中的源的編譯定義列表。這些會以``-D``標志或同等方式傳遞給編譯器,順序不定。
在編譯``SHARED``庫、
MODULE``庫或開啟`:prop_tgt:`ENABLE_EXPORTS`的可執行文件的來源時,CMake會自動定義一個目標特定的預處理器符號。默認情況下,該定義的形式為``<target>_EXPORTS,但可以通過`:prop_tgt:`DEFINE_SYMBOL`目標屬性覆蓋掉。這允許頭文件檢測它們是否從內部實施來源包含,並正確設置導出/導入註釋或符號的可見性。COMPILE_OPTIONS用於編譯目標中的源的編譯選項列表。這些以標志形式傳遞給編譯器,按出現順序排列。
編譯選項會自動對外殼跳脫。
某些編譯選項最好通過專用設定來指定,例如
POSITION_INDEPENDENT_CODE目標屬性。COMPILE_FEATURES在 3.1 版被加入.
用於編譯目標源所需的
編譯功能列表。通常,這些確保目標的源以足夠的語言標準級別編譯。INCLUDE_DIRECTORIES用於編譯目標源的包含目錄列表。這些由``-I``或``-isystem``旗標或同等旗標,按出現順序傳遞給編譯器。
為方便起見,可以啟用
CMAKE_INCLUDE_CURRENT_DIR變量以將源目錄和相應的構建目錄添加為所有目標上的INCLUDE_DIRECTORIES。SOURCES与目标关联的源文件列表。这包括目标创建时通过:command:add_executable、:command:add_library`或:command:`add_custom_target`指定的源,也包括由:command:`target_sources`命令添加的源,但不包括:ref:`文件集。
PRECOMPILE_HEADERS在 3.16 版被加入.
預編譯並包含在目標中編譯源文件時的頭文件列表。
COMPILE_WRAPPERS在 4.5 版被加入.
List of wrapper names to be prepended to the compile commands for a target's sources. See also
CMAKE_COMPILE_WRAPPER_<NAME>.AUTOMOC_MACRO_NAMES在 3.10 版被加入.
由:prop_tgt:`AUTOMOC`使用的宏名稱列表,以確定目標中的C++源是否需要經過``moc``處理。
AUTOUIC_OPTIONS在 3.0 版被加入.
在調用``uic``時,:prop_tgt:`AUTOUIC`使用的選項列表。
目標連結屬性¶
这些代表了连接目标的`构建规范 <目标构建规范>`_。
LINK_LIBRARIES連接目標的鏈接庫列表,如果它是可執行文件,共享庫或模塊庫。靜態庫`_和`共享庫`_的條目將通過指向其鏈接工件的路徑或`-l``旗標或等效旗標傳遞給鏈接器。而`對象庫`_的條目則是通過對象文件的路徑傳遞給鏈接器。
此外,用于编译和链接目标本身的`使用要求 <目标使用要求>`_会通过``LINK_LIBRARIES``条目指定的`静态库`_、共享库、接口库、对象库`_及`已引入目标`_的传递闭包进行传播,并集合在其:prop_tgt:`INTERFACE_LINK_LIBRARIES`属性中。
LINK_DIRECTORIES在 3.13 版被加入.
鏈接目標的鏈接目錄列表,如果它是可執行文件,共享庫或模塊庫。 目錄通過``-L``標誌或等效旗標傳遞給鏈接程序。
LINK_OPTIONS在 3.13 版被加入.
鏈接目標的鏈接選項列表,如果它是可執行文件,共享庫或模塊庫。 這些選項按出現順序作為旗標傳遞給鏈接程序。
鏈接選項被自動轉義以適應shell。
LINK_DEPENDS链接目标所依赖的文件列表(如果它是可执行文件、共享库或模块库)。例如,通过:prop_tgt:`LINK_OPTIONS`指定的链接脚本可能会在此列出,这样在更改它们时会导致二进制文件重新链接。
LINK_WRAPPERS在 4.5 版被加入.
List of wrapper names to be prepended to the link command for a target's output artifact, if it is an executable, shared library, or module library. See also
CMAKE_LINK_WRAPPER_<NAME>.
目標使用要求¶
目标的*使用要求*是通过:command:`target_link_libraries`链接到目标以确保正确编译和链接而传递给消费者的设置。它们由传递的`编译 <传递编译属性>`_和`链接 <传递链接属性>`_属性表示。
請注意,使用要求並不是為了僅出於便利而讓下游使用特定的:prop_tgt:COMPILE_OPTIONS、:prop_tgt:`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``。
通常,應該在使用:command:`target_link_libraries`時指定``PRIVATE``關鍵詞,如果某依賴項僅由庫的實現使用,而不是在頭文件中。如果某依賴項還在庫的頭文件中使用(例如用於類繼承),則應將其指定為``PUBLIC``依賴。僅由頭文件使用而不由庫實現使用的依賴應指定為``INTERFACE``依賴。 :command:`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>)
請注意,指定用於使用:command:install(EXPORT)`命令安裝導出的目標的使用要求時,必須謹慎。請參閱 :ref:`創建包 以獲取更多信息。
傳遞編譯屬性¶
这些代表用于编译消费者的`使用要求 <目标使用要求>`_。
INTERFACE_COMPILE_DEFINITIONS目標消費者中用於編譯源文件的編譯定義列表。通常這些是由目標的頭文件使用。
INTERFACE_COMPILE_OPTIONS目標消費者中用於編譯源文件的編譯選項列表。
INTERFACE_COMPILE_FEATURES在 3.1 版被加入.
目標消費者中用於編譯源文件所需的:manual:`編譯特性 <cmake-compile-features(7)>`列表。 通常這些可確保在編譯消費者時使用足夠的語言標準水平處理目標的頭文件。
INTERFACE_INCLUDE_DIRECTORIES目標消費者中用於編譯源文件的包含目錄列表。 通常這些是目標的頭文件的位置。
INTERFACE_SYSTEM_INCLUDE_DIRECTORIES当指定为包含目录时,例如通过:prop_tgt:`INCLUDE_DIRECTORIES`或:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`进行指定,在编译目标的消费者的源文件时应将以下目录视为“系统”包含目录的列表。
INTERFACE_SOURCES要與目標消費者關聯的源文件列表。
INTERFACE_PRECOMPILE_HEADERS在 3.16 版被加入.
目標消費者中用於編譯源文件時要預編譯和包含的頭文件列表。
INTERFACE_COMPILE_WRAPPERS在 4.5 版被加入.
List of wrapper names to be prepended to the compile commands when compiling sources in the target's consumers. See also
CMAKE_COMPILE_WRAPPER_<NAME>.INTERFACE_AUTOMOC_MACRO_NAMES在 3.27 版被加入.
由:prop_tgt:`AUTOMOC`使用的宏名稱列表,以確定C++源文件在目標的消費者中是否需要經過``moc``處理。
INTERFACE_AUTOUIC_OPTIONS在 3.0 版被加入.
在調用``uic``時,:prop_tgt:`AUTOUIC`使用的選項列表。
傳遞鏈接屬性¶
这些代表用于链接消费者的`使用要求 <目标使用要求>`_。
INTERFACE_LINK_LIBRARIES鏈接目標的消費者的鏈接庫列表,對於可執行文件,共享庫或模塊庫而言。這些是目標的傳遞依賴。
此外,对于编译和链接目标的消费者,使用要求 <目标使用要求_>`_从``INTERFACE_LINK_LIBRARIES``条目命名的`静态库、共享库、接口库、对象库、`已引入目标`_的传递闭包中收集,
INTERFACE_LINK_DIRECTORIES在 3.13 版被加入.
鏈接目標消費者的鏈接目錄列表,對於那些是可執行文件、共享庫或模塊庫的。
INTERFACE_LINK_OPTIONS在 3.13 版被加入.
鏈接目標消費者的鏈接選項列表,對於那些是可執行文件、共享庫或模塊庫的。
INTERFACE_LINK_DEPENDS在 3.13 版被加入.
鏈接目標消費者依賴的文件列表,對於可執行文件、共享庫或模塊庫而言。
INTERFACE_LINK_WRAPPERS在 4.5 版被加入.
List of wrapper names to be prepended to the link commands for a target's consumers' output artifact, for those that are executables, shared libraries, and module libraries. See also
CMAKE_LINK_WRAPPER_<NAME>.
自定義傳遞屬性¶
在 3.30 版被加入.
`:genex:`TARGET_PROPERTY`生成器表达式用于将上述`构建规格 <目标构建规格>`_及`使用要求 <目标使用要求>`_属性视为内建的传递属性进行评估。它还支持在目标及其链接依赖项上定义的:prop_tgt:`TRANSITIVE_COMPILE_PROPERTIES`和:prop_tgt:`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`目標屬性可能指定一個布爾值來表明一個目標是否應該以位置無關代碼編譯,這具有特定於平臺的影響。目標還可以指定使用要求 :prop_tgt:`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``都將編譯為位置無關代碼。由於這是對於``SHARED``庫的默認設置,``lib1``也將編譯為位置無關代碼。若依賴有衝突且不兼容的要求,:manual:`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``目標的:prop_tgt:`POSITION_INDEPENDENT_CODE`屬性不兼容。該庫要求消費者以位置無關代碼形式構建,而可執行文件則指定不構建為位置無關代碼,因此發出診斷。
``lib1``和``lib2``的要求不兼容。某一项要求消费者以位置无关代码形式构建,而另一项要求消费者不构建为位置无关代码。由于``exe2``同时链接到且彼此存在冲突,CMake发出错误消息::
CMake 错误:"lib2"的INTERFACE_POSITION_INDEPENDENT_CODE属性不符合"exe2"已确定的 POSITION_INDEPENDENT_CODE值。
為了“兼容”,POSITION_INDEPENDENT_CODE`屬性,如果設置,必須與所有設置了該屬性的傳遞指定依賴項中的 :prop_tgt:`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
非布爾屬性還可以參與“兼容界面”計算。屬性必須在 :prop_tgt:`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 来计算依赖关系属性的数值最小值。
每个计算得出的 "compatible" 属性值可在生成时使用生成器表达式在消费端读取。
注意,对于每个依赖项,在每个兼容接口属性中指定的属性集不应与任何其他属性中指定的集相交。
属性起源调试¶
由于构建规范可以通过依赖关系确定,缺乏生成目标的本地性和负责设置构建规范的代码,可能会使代码更难推理。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,调试输出显示来自每个依赖关系的属性值,以及该值是否决定了新的极限。
使用生成器表達式的建置規範¶
构建规范可以使用 生成器表达式,其中的内容可能根据条件或仅在生成时是已知的。例如,属性的计算 "compatible" 值可使用 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 编译,因为策略 CMP0182 在创建 shared_lib 目标时是 NEW。
``BUILD_INTERFACE``表达式包裹的需求仅在从同一构建系统中的目标消费或从导出到构建目录的目标消费时使用;``INSTALL_INTERFACE``表达式包裹的需求则是仅在已安装并使用命令:command:`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
相對路徑
)
相对路径按照命令出现的源目录进行解释。在 IMPORTED 目标的 INTERFACE_INCLUDE_DIRECTORIES 中不允许使用相对路径。
在使用非平凡生成表达式的情况下,可以在 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 附加到由 install(EXPORT) 生成的每个已安装 IMPORTED 目标的 INTERFACE_INCLUDE_DIRECTORIES。
当 导入的目标 的 INTERFACE_INCLUDE_DIRECTORIES 被消费时,该属性中的条目可以被视为系统包含目录。其效果取决于工具链,但一个常见的效果是忽略在这些目录中找到的头文件的编译器警告。已安装目标的 SYSTEM 属性决定这种行为(有关如何修改目标的已安装值,请参阅 EXPORT_NO_SYSTEM 属性)。也可以通过在 consumer 上设置 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 平台之间有所不同。包括 Cygwin 在内的所有基于 Windows 的系统都是 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 上:由
add_library()命令使用SHARED选项创建并且其ENABLE_EXPORTS目标属性设置时的共享库目标的链接器导入文件(例如.tbd)。
:prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY`和:prop_tgt:`ARCHIVE_OUTPUT_NAME`目標屬性可用於控制建置樹中的歸檔輸出項目位置和名稱。
目錄作用域的命令¶
:command:`target_include_directories、:command:`target_compile_definitions`和target_compile_options`命令仅对单一目标产生作用。`add_compile_definitions()、`add_compile_options`和`include_directories`命令具有类似功能,但为便捷起见适用于目录范围而不是目标范围。
建置組態¶
配置决定某种构建类型的规格,如``Release``或``Debug``。指定方式取决于所用的`:manual:生成器<cmake-generators(7)>`的类型。对于单一配置生成器,如Makefile 向导`和忍者,在配置时通过`:variable:CMAKE_BUILD_TYPE`变量指定配置。对于多配置生成器,如Visual Studio、:generator:`Xcode`和Ninja Multi-Config,用户可在构建时选择配置,而`:variable:CMAKE_BUILD_TYPE`会被忽略。多配置情况下,配置集合在配置时由:variable:`CMAKE_CONFIGURATION_TYPES`变量指定,但实际使用配置只会在构建阶段方能确定。这种差异往往容易被误解,导致如以下代码所示的问题出现:
# 警告:這對於多配置生成器是錯誤的,因為它們不使用並且通常甚至不設置CMAKE_BUILD_TYPE
string(TOLOWER ${CMAKE_BUILD_TYPE} build_type)
if (build_type STREQUAL debug)
target_compile_definitions(exe1 PRIVATE DEBUG_BUILD)
endif()
相反,應使用`:manual:`生成器表達式 <cmake-generator-expressions(7)>`來正確處理配置特定的邏輯,而不管所使用的生成器。 例如:
# 對於單配置和多配置生成器都正確運行
target_compile_definitions(exe1 PRIVATE
$<$<CONFIG:Debug>:DEBUG_BUILD>
)
在存在`:prop_tgt:已引入的`目标的情况时,MAP_IMPORTED_CONFIG_DEBUG < MAP_IMPORTED_CONFIG_< CONFIG>>`的内容也会被上文:genex:`$ < CONFIG:Debug>`表达式纳入考量。
大小寫敏感度¶
CMAKE_BUILD_TYPE`和:variable:`CMAKE_CONFIGURATION_TYPES`就像其他變數一樣,與它們的值進行的任何字符串比較都將是大小寫敏感的。:genex:`$<CONFIG>`生成器表達式也保留了由用戶或CMake默認設置的配置的大小寫。例如:
# 注意:不要使用這些模式,它們僅用於說明。
set(CMAKE_BUILD_TYPE Debug)
if(CMAKE_BUILD_TYPE STREQUAL DEBUG)
# ... 永遠到不了這裡,"Debug" != "DEBUG"
endif()
add_custom_target(print_config ALL
# 在這單一配置情況下顯示"Config is Debug"
COMMAND ${CMAKE_COMMAND} -E echo "Config is $<CONFIG>"
VERBATIM
)
set(CMAKE_CONFIGURATION_TYPES Debug Release)
if(DEBUG IN_LIST CMAKE_CONFIGURATION_TYPES)
# ... 永遠到不了這裡,"Debug" != "DEBUG"
endif()
相反,CMake內部在使用它進行更改行為的地方對配置類型是不區分大小寫的。例如,:genex:`$<CONFIG:Debug>`生成器表達式將對於配置的結果為`Debug、DEBUG、debug`甚至`DeBuG`值為1。因此,你可以用任意大小寫混合方式在CMAKE_BUILD_TYPE`和:variable:`CMAKE_CONFIGURATION_TYPES`中指定配置類型,儘管有強烈的慣例(見下一節)。如果必須在字符串比較中測試數值,則應先將數值轉換為大寫或小寫,並相應調整測試。
默認與自訂組態¶
默認情況下,CMake 定義了許多標準組態:
DebugDebugRelWithDebInfoRelWithDebInfo
在多組態生成器中,`:variable:`CMAKE_CONFIGURATION_TYPES`變數將默認填充為上述列表(可能是一個子集),除非由專案或用戶重寫。實際使用的配置由用戶在構建時選擇。
對於單配置生成器,組態在配置時間用`:variable:`CMAKE_BUILD_TYPE`變數指定且不能在建置時更改。默認值通常不是上述標準配置中的任何一個,而是空字符串。一種常見的誤解是這與“Debug”相同,但情況並非如此。用戶應始終明確指定構建類型以避免此常見問題。
上述標準配置類型在大多數平台上提供合理的行為,但它們可以擴展以提供其他類型。每個配置都為所用語言定義一組編譯器和鏈接器旗標變量。這些變量遵循`:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>`約定,其中`<CONFIG>`始終是大寫的配置名稱。在定義自定義組態類型時,確保正確設定這些變數,通常作為緩存變量。
偽目標¶
某些目標類型不代表構建系統的輸出,而僅代表輸入,如外部依賴、別名或其他非構建工件。偽目標不在生成的構建系統中表示。
匯入目標¶
:prop_tgt:`引入的`目标表示已有依赖。通常这样的目标由上游包定义并应被视为不可改变。声明一个已引入的`目标后,可以像常规目标一样使用如target_compile_definitions()、:command:`target_include_directories、:command:`target_compile_options`或:command:`target_link_libraries`等常用命令调整其目标属性。
IMPORTED`目標可能具有與二進制目標相同的使用要求屬性,如:INTERFACE_INCLUDE_DIRECTORIES, :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS, :prop_tgt:`INTERFACE_COMPILE_OPTIONS, :prop_tgt:`INTERFACE_LINK_LIBRARIES 和 :prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE。
尽管很少需从引入的目标读取`LOCATION`,但也可以这么做。诸如`:command:添加自定义命令`的命令可以透明地用引入的:prop_tgt:`可执行<TYPE>`目标作为``命令``可执行文件。
`:prop_tgt:`IMPORTED`目標的定義範圍是它被定義的目錄。可以從子目錄中存取和使用,但不能從父目錄或同級目錄中存取。其範圍類似於cmake變數的範圍。
還可以定義一個“GLOBAL”`:prop_tgt:`IMPORTED`目標,這在建置系統中可以全域存取。
根据`:manual:cmake-packages(7)`手册查看更多有关使用:prop_tgt:`引入的`目标创建软件包的信息。
別名目標¶
``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”目標,它可以是來自包的`:prop_tgt:`IMPORTED`目標,或者是作為同一構建系統一部分構建的“ALIAS”目標。
if (NOT TARGET Upstream::lib1)
find_package(lib1 REQUIRED)
endif()
add_executable(exe1 exe1.cpp)
target_link_libraries(exe1 Upstream::lib1)
ALIAS targets are not mutable, installable or exportable. They are
entirely local to the buildsystem description.
在 4.5 版的變更: ALIAS targets may be used as the operand for set_property() and
similar commands used to modify properties of targets. The
install() and export() commands may also use an ALIAS
target as the operand. The commands operate on the target which the alias
references. CMake 4.4 and earlier did not allow modifying, installing,
or exporting targets via an ALIAS.
A name can be tested for whether it is an ALIAS name by reading the
ALIASED_TARGET property from it:
get_target_property(_aliased Upstream::lib1 ALIASED_TARGET)
if(_aliased)
message(STATUS "名稱 Upstream::lib1是 ${_aliased} 的別名。")
endif()
介面庫¶
"INTERFACE" 載體目標不編譯來源,且不生成磁碟上圖書檔,故無`:prop_tgt:LOCATION。
它可以指定`使用需求 <目标使用需求>`_,兼容接口属性,和`自定义传递属性 <自定义传递属性>`_。仅``INTERFACE``模式下:command:target_include_directories、:command:target_compile_definitions、:command:target_compile_options、:command:`target_sources`和:command:`target_link_libraries`命令可以与``INTERFACE``库一起使用。
從CMake 3.19開始,"INTERFACE"載體目標可能可選包含來源檔案。含有來源檔案的介面載體將會作為建置目標包含於生成的建置系統中。儘管它不編譯來源,也可能包含自定義指令用於生成其他來源。此外,IDE會將來源檔案作為載體的一部分顯示,以供互動式讀取和編輯。
"INTERFACE" 資料庫的主要用途是僅頭文件型資料庫。自 CMake 3.23 起,頭文件可以通過`:command:`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``中。安裝目標自動成為互換工作的使用要求中的包含目錄。
介面庫上允許的屬性¶
自CMake 3.19以來,介面庫允許像其他目標類型一樣,設定或閱讀具有任何名稱的目標屬性。
在CMake 3.19以前,介面庫僅允許撰寫或讀取具有有限名稱集的目標屬性:
以``INTERFACE_``前端命名的屬性,無論是內置`使用要求 <Target Usage Requirements>`_,還是個性化名稱。
内建属性以``COMPATIBLE_INTERFACE_``前缀命名(兼容接口属性)。
內置屬性`:prop_tgt:NAME、:prop_tgt:`EXPORT_NAME、:prop_tgt:`EXPORT_PROPERTIES、:prop_tgt:`MANUALLY_ADDED_DEPENDENCIES、:prop_tgt:`IMPORTED、:prop_tgt:`IMPORTED_LIBNAME_<CONFIG> 和 :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>。
在 3.11 版被加入: 以首字下劃線(
_)或 ASCII 小寫字母命名的屬性。
Preparation Targets¶
The Ninja 生成器, Makefile 生成器, and
FASTBuild generator provide convenience targets that build only
the prerequisites of a later step, such as running tests or installing.
Test Preparation Targets¶
在 4.4 版被加入.
The generators which support preparation targets provide convenience build
targets that build the known prerequisites of tests before running the tests,
unless CMAKE_SKIP_TEST_PREP_TARGETS is enabled:
test_prep/all準備執行所有測試。
test_prep/<name>Prepare to run the test
<name>. If multiple tests in different directories share the same name, their dependencies are merged into a singletest_prep/<name>target.
Building a test preparation target ensures that the test executable is up-to-date before the test runs.
A test preparation target is generated only when its name can be represented safely by the native build tool, as described under 目標名稱. CMake warns about a test that has build dependencies but whose name cannot be represented.
CMake infers dependencies associated with tests from the test executable, as
well as any targets referenced by the test command via generator expressions.
The BUILD_DEPENDS option of the add_test() command can be used to
add explicit build dependencies.
How file dependencies are prepared depends on how the file is produced. See Preparation Target File Dependencies.
在 4.5 版被加入: Modules may also extend test_prep/all with directory-scoped dependencies
via the CMAKE_TEST_BUILD_DEPENDS directory property.
在 4.5 版的變更: Test preparation targets are enabled by default. FASTBuild and
the Makefile 生成器 gained support for test preparation targets.
Previously, test preparation targets were only enabled if the
CMAKE_TEST_BUILD_DEPENDS variable was enabled.
安裝準備目標¶
在 4.5 版被加入.
If the project has install rules, the generators which support preparation
targets provide convenience build targets that build the known prerequisites
of an installation before running the installation, unless
CMAKE_SKIP_INSTALL_PREP_TARGETS or
CMAKE_SKIP_INSTALL_RULES is enabled:
install_prep/allPrepare for an installation that does not select a component, such as
cmake --install <build-dir>without--component. This includes rules of every component, but omitsinstall()rules using theEXCLUDE_FROM_ALLoption.install_prep/<component>Prepare to install
<component>. Rules for that component are included even when they use theEXCLUDE_FROM_ALLoption.
Building install_prep/all does not necessarily prepare the installation
of a particular component, because installing a component also runs that
component's EXCLUDE_FROM_ALL rules. Build the matching
install_prep/<component> target before installing a specific component.
例如:
cmake --build <build-dir> --config Release --target install_prep/Runtime
cmake --install <build-dir> --config Release --component Runtime
Only install rules active for the selected configuration contribute build dependencies. For multi-config generators, the same configuration should be used for the preparation and installation steps.
A component preparation target is generated only when its name can be represented safely by the native build tool, as described under 目標名稱. CMake warns about a component that has build dependencies but whose name cannot be represented.
備註
A component named all does not get its own target because its name would
conflict with install_prep/all. Its rules contribute to
install_prep/all only when they do not use the EXCLUDE_FROM_ALL
option.
CMake infers dependencies associated with installed target artifacts, imported runtime artifacts, runtime dependency sets, C++ module BMIs, and C++ module export metadata. Preparing BMIs or module export metadata builds the targets that produce them.
Installing files with the FILES or PROGRAMS signatures of the
install() command, or a target's file sets or its
PUBLIC_HEADER, PRIVATE_HEADER, or RESOURCE
files, implies build dependencies only for files that the build produces,
i.e., target output artifacts, and outputs and byproducts of custom commands
and custom targets. How such a file is prepared depends on how it is produced.
See Preparation Target File Dependencies.
Preparation Target File Dependencies¶
The manner in which a file dependency of a test or install preparation target is prepared depends on how it is produced:
A target's output artifact, such as one named by
TARGET_FILE, is prepared by building that target.A file that is the output of a custom command attached to exactly one target is prepared by running that custom command. The Makefile 生成器 cannot depend on individual files, so they build the target owning the custom command instead.
The target which installs the file (or the file set to which the file belongs), if any, is not built by installation preparation targets.
Any other generated file, such as a byproduct or the output of a custom command attached to more than one target, is prepared by depending on the file itself, which runs whatever produces it. The Makefile 生成器 and
FASTBuildcannot do so, so they warn.For install preparation targets, if a target installs the file (or the file set to which the file belongs), the preparation target will build that target instead, which must therefore depend on the producer, e.g., through
add_dependencies(). Otherwise, the preparation target does not prepare the file.
例如:
# Preparation which depends on `generated.h` runs only the custom command,
# not the library build.
add_custom_command(OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/generated.h"
COMMAND ...)
add_library(A a.c "${CMAKE_CURRENT_BINARY_DIR}/generated.h")
set_property(TARGET A PROPERTY PUBLIC_HEADER
"${CMAKE_CURRENT_BINARY_DIR}/generated.h")
# Preparation which depends on `byproduct.h` runs `gen`, or with some
# generators builds `B` instead, so `B` must depend on the producer of its
# byproduct.
add_custom_target(gen COMMAND ...
BYPRODUCTS "${CMAKE_CURRENT_BINARY_DIR}/byproduct.h")
add_library(B b.c)
add_dependencies(B gen)
# The preparation target for an install which installs `B` will implicitly
# depend on `byproduct.h` when it appears in an associated file set.
set_property(TARGET B PROPERTY PUBLIC_HEADER
"${CMAKE_CURRENT_BINARY_DIR}/byproduct.h")
# A test depending on `byproduct.h` needs to express that dependency
# explicitly using `BUILD_DEPENDS`.
add_test(test_B COMMAND test_B BUILD_DEPENDS
"${CMAKE_CURRENT_BINARY_DIR}/byproduct.h")
The BUILD_DEPENDS option of the FILES, PROGRAMS, DIRECTORY,
SCRIPT, and CODE signatures of the install() command can
be used to specify targets or files that CMake cannot infer. DIRECTORY,
SCRIPT, and CODE rules do not imply build dependencies without
BUILD_DEPENDS. The deprecated install_targets() command does not
contribute dependencies.
Install rules below a directory added with EXCLUDE_FROM_ALL are
ignored, matching installation from the parent directory.