cmake-generator-expressions(7)

簡介

產生器表達式在建置系統生成期間被評估,以產生每個建置組態特定的資訊。它們的形式為 $<...>。例如

target_include_directories(tgt PRIVATE /opt/include/$<CXX_COMPILER_ID>)

這會展開為 /opt/include/GNU/opt/include/Clang 等,取決於使用的 C++ 編譯器。

產生器表達式允許在許多目標屬性的上下文中使用,例如 LINK_LIBRARIESINCLUDE_DIRECTORIESCOMPILE_DEFINITIONS 以及其他。它們也可以在使用命令填充這些屬性時使用,例如 target_link_libraries()target_include_directories()target_compile_definitions() 以及其他。它們啟用條件式連結、編譯時使用的條件式定義、條件式包含目錄等等。這些條件可以基於建置組態、目標屬性、平台資訊或任何其他可查詢的資訊。

產生器表達式可以巢狀

target_compile_definitions(tgt PRIVATE
  $<$<VERSION_LESS:$<CXX_COMPILER_VERSION>,4.2.0>:OLD_COMPILER>
)

如果 CMAKE_CXX_COMPILER_VERSION 小於 4.2.0,則以上會展開為 OLD_COMPILER

空白字元與引號

產生器表達式通常在命令參數之後解析。如果產生器表達式包含空格、換行符號、分號或其他可能被解釋為命令參數分隔符號的字元,則在傳遞給命令時,整個表達式應以引號括起來。否則可能會導致表達式被分割,並且可能不再被識別為產生器表達式。

當使用 add_custom_command()add_custom_target() 時,請使用 VERBATIMCOMMAND_EXPAND_LISTS 選項以獲得穩健的參數分割和引號處理。

# WRONG: Embedded space will be treated as an argument separator.
# This ends up not being seen as a generator expression at all.
add_custom_target(run_some_tool
  COMMAND some_tool -I$<JOIN:$<TARGET_PROPERTY:tgt,INCLUDE_DIRECTORIES>, -I>
  VERBATIM
)
# Better, but still not robust. Quotes prevent the space from splitting the
# expression. However, the tool will receive the expanded value as a single
# argument.
add_custom_target(run_some_tool
  COMMAND some_tool "-I$<JOIN:$<TARGET_PROPERTY:tgt,INCLUDE_DIRECTORIES>, -I>"
  VERBATIM
)
# Nearly correct. Using a semicolon to separate arguments and adding the
# COMMAND_EXPAND_LISTS option means that paths with spaces will be handled
# correctly. Quoting the whole expression ensures it is seen as a generator
# expression. But if the target property is empty, we will get a bare -I
# with nothing after it.
add_custom_target(run_some_tool
  COMMAND some_tool "-I$<JOIN:$<TARGET_PROPERTY:tgt,INCLUDE_DIRECTORIES>,;-I>"
  COMMAND_EXPAND_LISTS
  VERBATIM
)

使用變數來建構更複雜的產生器表達式也是減少錯誤和提高可讀性的好方法。以上範例可以進一步改進如下

# The $<BOOL:...> check prevents adding anything if the property is empty,
# assuming the property value cannot be one of CMake's false constants.
set(prop "$<TARGET_PROPERTY:tgt,INCLUDE_DIRECTORIES>")
add_custom_target(run_some_tool
  COMMAND some_tool "$<$<BOOL:${prop}>:-I$<JOIN:${prop},;-I>>"
  COMMAND_EXPAND_LISTS
  VERBATIM
)

最後,以上範例可以使用替代的產生器表達式以更簡單和穩健的方式表示

add_custom_target(run_some_tool
  COMMAND some_tool "$<LIST:TRANSFORM,$<TARGET_PROPERTY:tgt,INCLUDE_DIRECTORIES>,PREPEND,-I>"
  COMMAND_EXPAND_LISTS
  VERBATIM
)

一個常見的錯誤是嘗試使用縮排將產生器表達式跨越多行分割

# WRONG: New lines and spaces all treated as argument separators, so the
# generator expression is split and not recognized correctly.
target_compile_definitions(tgt PRIVATE
  $<$<AND:
      $<CXX_COMPILER_ID:GNU>,
      $<VERSION_GREATER_EQUAL:$<CXX_COMPILER_VERSION>,5>
    >:HAVE_5_OR_LATER>
)

再次強調,請使用名稱明確的輔助變數來建構可讀的表達式

set(is_gnu "$<CXX_COMPILER_ID:GNU>")
set(v5_or_later "$<VERSION_GREATER_EQUAL:$<CXX_COMPILER_VERSION>,5>")
set(meet_requirements "$<AND:${is_gnu},${v5_or_later}>")
target_compile_definitions(tgt PRIVATE
  "$<${meet_requirements}:HAVE_5_OR_LATER>"
)

除錯

由於產生器表達式是在建置系統生成期間評估的,而不是在處理 CMakeLists.txt 檔案期間評估的,因此無法使用 message() 命令檢查其結果。一種產生除錯訊息的可能方法是新增自訂目標

add_custom_target(genexdebug COMMAND ${CMAKE_COMMAND} -E echo "$<...>")

在執行 cmake 之後,您可以建置 genexdebug 目標以印出 $<...> 表達式的結果(即執行命令 cmake --build ... --target genexdebug)。

另一種方法是使用 file(GENERATE) 將除錯訊息寫入檔案

file(GENERATE OUTPUT filename CONTENT "$<...>")

產生器表達式參考

注意

本參考文件與 CMake 大部分文件不同,它省略了佔位符(例如 conditionstringtarget 等)周圍的角括號 <...>。這是為了防止這些佔位符被誤解為產生器表達式。

條件表達式

產生器表達式的一個基本類別與條件邏輯有關。支援兩種形式的條件產生器表達式

$<condition:true_string>

如果 condition1,則評估為 true_string,如果 condition 評估為 0,則評估為空字串。任何其他 condition 值都會導致錯誤。

$<IF:condition,true_string,false_string>

在版本 3.8 中新增。

如果 condition1,則評估為 true_string,如果 condition0,則評估為 false_string。任何其他 condition 值都會導致錯誤。

在版本 3.28 中新增: 此產生器表達式會短路,因此當 condition1 時,false_string 中的產生器表達式不會被評估,而當條件為 0 時,true_string 中的產生器表達式不會被評估。

通常,condition 本身就是一個產生器表達式。例如,以下表達式在使用 Debug 組態時展開為 DEBUG_MODE,對於所有其他組態則展開為空字串

$<$<CONFIG:Debug>:DEBUG_MODE>

除了 10 之外的布林值 condition 值可以使用 $<BOOL:...> 產生器表達式包裝來處理

$<BOOL:string>

string 轉換為 01。如果以下任何條件為真,則評估為 0

  • string 為空,

  • string 不區分大小寫地等於 0FALSEOFFNNOIGNORENOTFOUND,或

  • string 以字尾 -NOTFOUND 結尾(區分大小寫)。

否則評估為 1

$<BOOL:...> 產生器表達式通常在 condition 由 CMake 變數提供時使用

$<$<BOOL:${HAVE_SOME_FEATURE}>:-DENABLE_SOME_FEATURE>

邏輯運算子

支援常見的布林邏輯運算子

$<AND:conditions>

其中 conditions 是以逗號分隔的布林表達式列表,所有這些表達式都必須評估為 10。如果所有條件都為 1,則整個表達式評估為 1。如果任何條件為 0,則整個表達式評估為 0

$<OR:conditions>

其中 conditions 是以逗號分隔的布林表達式列表。所有這些表達式都必須評估為 10。如果至少一個 conditions1,則整個表達式評估為 1。如果所有 conditions 都評估為 0,則整個表達式評估為 0

$<NOT:condition>

condition 必須為 01。如果 condition1,則表達式的結果為 0,否則為 1

在版本 3.28 中新增: 邏輯運算子會短路,因此一旦可以確定回傳值,參數列表中的產生器表達式將不會被評估。

主要比較表達式

CMake 支援各種比較事物的產生器表達式。本節涵蓋主要和最廣泛使用的比較類型。其他更具體的比較類型記錄在下面各自獨立的章節中。

字串比較

$<STREQUAL:string1,string2>

如果 string1string2 相等,則為 1,否則為 0。比較是區分大小寫的。對於不區分大小寫的比較,請與 字串轉換產生器表達式 結合使用。例如,如果 ${foo}BARBarbar 等任何一個,則以下評估為 1

$<STREQUAL:$<UPPER_CASE:${foo}>,BAR>
$<EQUAL:value1,value2>

如果 value1value2 在數值上相等,則為 1,否則為 0

版本比較

$<VERSION_LESS:v1,v2>

如果 v1 是比 v2 更低的版本,則為 1,否則為 0

$<VERSION_GREATER:v1,v2>

如果 v1 是比 v2 更高的版本,則為 1,否則為 0

$<VERSION_EQUAL:v1,v2>

如果 v1v2 是相同的版本,則為 1,否則為 0

$<VERSION_LESS_EQUAL:v1,v2>

在版本 3.7 中新增。

如果 v1 是版本小於或等於 v2,則為 1,否則為 0

$<VERSION_GREATER_EQUAL:v1,v2>

在版本 3.7 中新增。

如果 v1 是版本大於或等於 v2,則為 1,否則為 0

字串轉換

$<LOWER_CASE:string>

string 的內容轉換為小寫。

$<UPPER_CASE:string>

string 的內容轉換為大寫。

$<MAKE_C_IDENTIFIER:...>

... 的內容轉換為 C 識別符號。轉換遵循與 string(MAKE_C_IDENTIFIER) 相同的行為。

列表達式

本節中的大多數表達式都與 list() 命令密切相關,提供相同的功能,但採用產生器表達式的形式。

在以下每個與列表相關的產生器表達式中,如果該產生器表達式期望在 list 之後提供某些內容,則 list 不得包含任何逗號。例如,表達式 $<LIST:FIND,list,value> 需要在 list 之後有一個 value。由於逗號用於分隔 listvalue,因此 list 本身不能包含逗號。此限制不適用於 list() 命令,它僅適用於列表處理產生器表達式。

列表比較

$<IN_LIST:string,list>

在版本 3.12 中新增。

如果 string 是以分號分隔的 list 中的一個項目,則為 1,否則為 0。它使用區分大小寫的比較。

列表查詢

$<LIST:LENGTH,list>

在版本 3.27 中新增。

list 中項目的數量。

$<LIST:GET,list,index,...>

在版本 3.27 中新增。

展開為從 list 中由索引指定的項目列表。

$<LIST:SUBLIST,list,begin,length>

在版本 3.27 中新增。

給定 list 的子列表。如果 length 為 0,將回傳空列表。如果 length 為 -1 或列表小於 begin + length,則將回傳從 begin 開始的列表剩餘項目。

$<LIST:FIND,list,value>

在版本 3.27 中新增。

list 中具有指定 value 的第一個項目的索引,如果 value 不在 list 中,則為 -1。

列表轉換

$<LIST:JOIN,list,glue>

在版本 3.27 中新增。

list 轉換為單一字串,並在每個項目之間插入 glue 字串的內容。這在概念上與 $<JOIN:list,glue> 操作相同,但兩者在處理空項目時的行為不同。$<LIST:JOIN,list,glue> 保留所有空項目,而 $<JOIN:list,glue> 會從列表中刪除所有空項目。

$<LIST:APPEND,list,item,...>

在版本 3.27 中新增。

將每個 item 附加到 list。多個項目應以逗號分隔。

$<LIST:PREPEND,list,item,...>

在版本 3.27 中新增。

將每個 item 插入到 list 的開頭。如果有多個項目,則應以逗號分隔,並且將保留前置項目的順序。

$<LIST:INSERT,list,index,item,...>

在版本 3.27 中新增。

item (或多個項目)插入到指定 indexlist。多個項目應以逗號分隔。

指定超出範圍的 index 是錯誤的。有效的索引為 0 到 N,其中 N 是列表的長度(包含)。空列表的長度為 0。

$<LIST:POP_BACK,list>

在版本 3.27 中新增。

list 中移除最後一個項目。

$<LIST:POP_FRONT,list>

在版本 3.27 中新增。

list 中移除第一個項目。

$<LIST:REMOVE_ITEM,list,value,...>

在版本 3.27 中新增。

list 中移除給定 value (或多個值)的所有實例。如果給定多個值,則應以逗號分隔。

$<LIST:REMOVE_AT,list,index,...>

在版本 3.27 中新增。

list 中移除每個給定 index 處的項目。

$<LIST:REMOVE_DUPLICATES,list>

在版本 3.27 中新增。

list 中移除所有重複的項目。項目的相對順序被保留,但如果遇到重複項,則僅保留第一個實例。結果與 $<REMOVE_DUPLICATES:list> 相同。

$<LIST:FILTER,list,INCLUDE|EXCLUDE,regex>

在版本 3.27 中新增。

來自 list 的項目列表,這些項目符合 (INCLUDE) 或不符合 (EXCLUDE) 正規表達式 regex。結果與 $<FILTER:list,INCLUDE|EXCLUDE,regex> 相同。

$<LIST:TRANSFORM,list,ACTION[,SELECTOR]>

在版本 3.27 中新增。

透過將 ACTION 應用於所有或透過指定 SELECTOR 應用於選定的列表項目來轉換 list

注意

TRANSFORM 子命令不會更改列表中項目的數量。如果指定了 SELECTOR,則只會更改某些項目,其他項目將保持與轉換前相同。

ACTION 指定要應用於列表項目的動作。這些動作的語義與 list(TRANSFORM) 命令完全相同。ACTION 必須是以下其中之一

APPENDPREPEND

將指定的值附加、前置到列表的每個項目。

$<LIST:TRANSFORM,list,(APPEND|PREPEND),value[,SELECTOR]>
TOLOWERTOUPPER

將列表的每個項目轉換為小寫、大寫字符。

$<LIST:TRANSFORM,list,(TOLOWER|TOUPPER)[,SELECTOR]>
STRIP

從列表的每個項目中移除開頭和結尾的空格。

$<LIST:TRANSFORM,list,STRIP[,SELECTOR]>
REPLACE

盡可能多次匹配正則表達式,並將替換表達式替換為列表中每個項目的匹配項。

$<LIST:TRANSFORM,list,REPLACE,regular_expression,replace_expression[,SELECTOR]>

SELECTOR 決定將轉換列表中的哪些項目。一次只能指定一種選擇器類型。如果給定 SELECTOR,則必須是以下其中之一

AT

指定索引列表。

$<LIST:TRANSFORM,list,ACTION,AT,index[,index...]>
FOR

指定一個範圍,可選擇使用增量來迭代該範圍。

$<LIST:TRANSFORM,list,ACTION,FOR,start,stop[,step]>
REGEX

指定正則表達式。只有與正則表達式匹配的項目才會被轉換。

$<LIST:TRANSFORM,list,ACTION,REGEX,regular_expression>
$<JOIN:list,glue>

使用 glue 字串的內容連接 list,字串內容會插入到每個項目之間。這在概念上與 $<LIST:JOIN,list,glue> 操作相同,但兩者在處理空項目時的行為有所不同。$<LIST:JOIN,list,glue> 保留所有空項目,而 $<JOIN,list,glue> 則從列表中刪除所有空項目。

$<REMOVE_DUPLICATES:list>

在版本 3.15 中新增。

移除給定 list 中的重複項目。項目的相對順序會被保留,如果遇到重複項,則只保留第一個實例。結果與 $<LIST:REMOVE_DUPLICATES,list> 相同。

$<FILTER:list,INCLUDE|EXCLUDE,regex>

在版本 3.15 中新增。

list 中包含或移除與正則表達式 regex 匹配的項目。結果與 $<LIST:FILTER,list,INCLUDE|EXCLUDE,regex> 相同。

列表排序

$<LIST:REVERSE,list>

在版本 3.27 中新增。

項目順序相反的 list

$<LIST:SORT,list[,(COMPARE:option|CASE:option|ORDER:option)]...>

在版本 3.27 中新增。

根據指定的選項排序的 list

使用 COMPARE 選項之一來選擇排序的比較方法

STRING

按字母順序排序字串列表。如果未給定 COMPARE 選項,這是預設行為。

FILE_BASENAME

依據檔案路徑的 basename 排序列表。

NATURAL

使用自然順序(請參閱 strverscmp(3) 的 man page)排序字串列表,以便將連續的數字作為整數進行比較。例如,如果選擇 NATURAL 比較,則以下列表 10.0 1.1 2.1 8.0 2.0 3.1 將被排序為 1.1 2.0 2.1 3.1 8.0 10.0,而使用 STRING 比較,它將被排序為 1.1 10.0 2.0 2.1 3.1 8.0

使用 CASE 選項之一來選擇區分大小寫或不區分大小寫的排序模式

SENSITIVE

列表項目以區分大小寫的方式排序。如果未給定 CASE 選項,這是預設行為。

INSENSITIVE

列表項目以不區分大小寫的方式排序。僅因大小寫而異的項目的順序未指定。

若要控制排序順序,可以給定 ORDER 選項之一

ASCENDING

以升序排序列表。當未給定 ORDER 選項時,這是預設行為。

DESCENDING

以降序排序列表。

選項可以按任何順序指定,但多次指定相同的選項是錯誤的。

$<LIST:SORT,list,CASE:SENSITIVE,COMPARE:STRING,ORDER:DESCENDING>

路徑表達式

本節中的大多數表達式都與 cmake_path() 命令密切相關,提供相同的功能,但採用生成器表達式的形式。

對於本節中的所有生成器表達式,路徑預期為 cmake 樣式格式。$<PATH:CMAKE_PATH> 生成器表達式可用於將原生路徑轉換為 cmake 樣式路徑。

路徑比較

$<PATH_EQUAL:path1,path2>

在版本 3.24 中新增。

比較兩個路徑的詞彙表示形式。不會對任何路徑執行正規化。如果路徑相等,則返回 1,否則返回 0

有關更多詳細信息,請參閱 cmake_path(COMPARE)

路徑查詢

這些表達式提供與 Query 選項等效的生成時功能,這些選項屬於 cmake_path() 命令。「所有」路徑都預期為 cmake 樣式格式。

$<PATH:HAS_*,path>

在版本 3.24 中新增。

如果特定的路徑組件存在,則以下操作返回 1,否則返回 0。有關每個路徑組件的含義,請參閱 路徑結構和術語

$<PATH:HAS_ROOT_NAME,path>
$<PATH:HAS_ROOT_DIRECTORY,path>
$<PATH:HAS_ROOT_PATH,path>
$<PATH:HAS_FILENAME,path>
$<PATH:HAS_EXTENSION,path>
$<PATH:HAS_STEM,path>
$<PATH:HAS_RELATIVE_PART,path>
$<PATH:HAS_PARENT_PATH,path>

請注意以下特殊情況

  • 對於 HAS_ROOT_PATH,只有在 root-nameroot-directory 中至少有一個非空時,才會返回 true 結果。

  • 對於 HAS_PARENT_PATH,根目錄也被認為具有父目錄,即它本身。除非路徑僅由 filename 組成,否則結果為 true。

$<PATH:IS_ABSOLUTE,path>

在版本 3.24 中新增。

如果路徑是絕對路徑,則返回 1,否則返回 0

$<PATH:IS_RELATIVE,path>

在版本 3.24 中新增。

這將返回與 IS_ABSOLUTE 相反的結果。

$<PATH:IS_PREFIX[,NORMALIZE],path,input>

在版本 3.24 中新增。

如果 pathinput 的前綴,則返回 1,否則返回 0

當指定 NORMALIZE 選項時,pathinput 在檢查之前會先進行正規化

路徑分解

這些表達式提供與 Decomposition 選項等效的生成時功能,這些選項屬於 cmake_path() 命令。「所有」路徑都預期為 cmake 樣式格式。

$<PATH:GET_*,...>

在版本 3.24 中新增。

以下操作從路徑中檢索不同的組件或組件群組。有關每個路徑組件的含義,請參閱 路徑結構和術語

在版本 3.27 中變更:所有操作現在都接受路徑列表作為參數。當指定路徑列表時,操作將應用於每個路徑。

$<PATH:GET_ROOT_NAME,path...>
$<PATH:GET_ROOT_DIRECTORY,path...>
$<PATH:GET_ROOT_PATH,path...>
$<PATH:GET_FILENAME,path...>
$<PATH:GET_EXTENSION[,LAST_ONLY],path...>
$<PATH:GET_STEM[,LAST_ONLY],path...>
$<PATH:GET_RELATIVE_PART,path...>
$<PATH:GET_PARENT_PATH,path...>

如果請求的組件在路徑中不存在,則返回空字串。

路徑轉換

這些表達式提供與 ModificationGeneration 選項等效的生成時功能,這些選項屬於 cmake_path() 命令。「所有」路徑都預期為 cmake 樣式格式。

在版本 3.27 中變更:所有操作現在都接受路徑列表作為參數。當指定路徑列表時,操作將應用於每個路徑。

$<PATH:CMAKE_PATH[,NORMALIZE],path...>

在版本 3.24 中新增。

返回 path。如果 path 是原生路徑,則會將其轉換為帶有正斜線 (/) 的 cmake 樣式路徑。在 Windows 上,會考慮長檔名標記。

當指定 NORMALIZE 選項時,路徑在轉換後會進行正規化

$<PATH:NATIVE_PATH[,NORMALIZE],path...>

在版本 4.0 中新增。

返回 path,並將其轉換為具有平台特定斜線的原生格式(Windows 主機上為 \,其他地方為 /)。

當指定 NORMALIZE 選項時,路徑在轉換之前會先進行正規化

$<PATH:APPEND,path...,input,...>

在版本 3.24 中新增。

使用 / 作為 directory-separator,將所有 input 參數附加到 path,並返回結果。根據 input 的不同,可能會捨棄 path 的值。

有關更多詳細信息,請參閱 cmake_path(APPEND)

$<PATH:REMOVE_FILENAME,path...>

在版本 3.24 中新增。

返回已移除檔名組件(由 $<PATH:GET_FILENAME> 返回)的 path。移除後,任何尾隨的 directory-separator(如果存在)都會保持不變。

有關更多詳細信息,請參閱 cmake_path(REMOVE_FILENAME)

$<PATH:REPLACE_FILENAME,path...,input>

在版本 3.24 中新增。

返回檔名組件已替換為 inputpath。如果 path 沒有檔名組件(即 $<PATH:HAS_FILENAME> 返回 0),則 path 保持不變。

有關更多詳細信息,請參閱 cmake_path(REPLACE_FILENAME)

$<PATH:REMOVE_EXTENSION[,LAST_ONLY],path...>

在版本 3.24 中新增。

返回已移除 extension(如果有的話)的 path

有關更多詳細信息,請參閱 cmake_path(REMOVE_EXTENSION)

$<PATH:REPLACE_EXTENSION[,LAST_ONLY],path...,input>

在版本 3.24 中新增。

返回 extension 已替換為 input(如果有的話)的 path

有關更多詳細信息,請參閱 cmake_path(REPLACE_EXTENSION)

$<PATH:NORMAL_PATH,path...>

在版本 3.24 中新增。

返回根據 正規化 中描述的步驟進行正規化的 path

$<PATH:RELATIVE_PATH,path...,base_directory>

在版本 3.24 中新增。

返回 path,已修改為相對於 base_directory 參數。

有關更多詳細信息,請參閱 cmake_path(RELATIVE_PATH)

$<PATH:ABSOLUTE_PATH[,NORMALIZE],path...,base_directory>

在版本 3.24 中新增。

返回絕對路徑的 path。如果 path 是相對路徑($<PATH:IS_RELATIVE> 返回 1),則會相對於 base_directory 參數指定的給定基準目錄進行評估。

當指定 NORMALIZE 選項時,路徑在路徑計算後會進行正規化

有關更多詳細信息,請參閱 cmake_path(ABSOLUTE_PATH)

Shell 路徑

$<SHELL_PATH:...>

在版本 3.4 中新增。

轉換為 shell 路徑樣式的 ... 內容。例如,在 Windows shell 中,斜線會轉換為反斜線,而在 MSYS shell 中,磁碟機代號會轉換為 posix 路徑。... 必須是絕對路徑。

在版本 3.14 中新增:... 可以是以分號分隔的路徑列表,在這種情況下,每個路徑都會單獨轉換,並使用 shell 路徑分隔符(POSIX 上為 :,Windows 上為 ;)生成結果列表。請務必將包含此 genex 的參數用雙引號括起來,以便 ; 不會拆分參數。

組態表達式

$<CONFIG>

組態名稱。使用此項代替已棄用的 CONFIGURATION 生成器表達式。

$<CONFIG:cfgs>

如果組態是逗號分隔列表 cfgs 中的任何一個條目,則為 1,否則為 0。這是區分大小寫的比較。MAP_IMPORTED_CONFIG_<CONFIG> 中的映射在評估 IMPORTED 目標的屬性時也會被此表達式考慮在內。

在版本 3.19 中變更:可以為 cfgs 指定多個組態。CMake 3.18 及更早版本僅接受單個組態。

$<OUTPUT_CONFIG:...>

在版本 3.20 中新增。

僅在 add_custom_command()add_custom_target() 中作為參數的最外層生成器表達式有效。使用 Ninja Multi-Config 生成器,... 中的生成器表達式會使用自定義命令的「輸出組態」進行評估。對於其他生成器,... 的內容會正常評估。

$<COMMAND_CONFIG:...>

在版本 3.20 中新增。

僅在 add_custom_command()add_custom_target() 中作為參數的最外層生成器表達式有效。使用 Ninja Multi-Config 生成器,... 中的生成器表達式會使用自定義命令的「命令組態」進行評估。對於其他生成器,... 的內容會正常評估。

工具鏈和語言表達式

平台

$<PLATFORM_ID>

當前系統的 CMake 平台 ID。另請參閱 CMAKE_SYSTEM_NAME 變數。

$<PLATFORM_ID:platform_ids>

如果 CMake 的平台 ID 與逗號分隔列表 platform_ids 中的任何一個條目匹配,則為 1,否則為 0。另請參閱 CMAKE_SYSTEM_NAME 變數。

編譯器版本

另請參閱 CMAKE_<LANG>_COMPILER_VERSION 變數,它與本小節中的表達式密切相關。

$<C_COMPILER_VERSION>

使用的 C 編譯器版本。

$<C_COMPILER_VERSION:version>

如果 C 編譯器的版本與 version 匹配,則為 1,否則為 0

$<CXX_COMPILER_VERSION>

使用的 CXX 編譯器版本。

$<CXX_COMPILER_VERSION:version>

如果 C++ 編譯器的版本與 version 匹配,則為 1,否則為 0

$<CUDA_COMPILER_VERSION>

在版本 3.15 中新增。

使用的 CUDA 編譯器版本。

$<CUDA_COMPILER_VERSION:version>

在版本 3.15 中新增。

如果 C++ 編譯器的版本與 version 匹配,則為 1,否則為 0

$<OBJC_COMPILER_VERSION>

在版本 3.16 中新增。

使用的 Objective-C 編譯器版本。

$<OBJC_COMPILER_VERSION:version>

在版本 3.16 中新增。

如果 Objective-C 編譯器的版本與 version 匹配,則為 1,否則為 0

$<OBJCXX_COMPILER_VERSION>

在版本 3.16 中新增。

使用的 Objective-C++ 編譯器版本。

$<OBJCXX_COMPILER_VERSION:version>

在版本 3.16 中新增。

如果 Objective-C++ 編譯器的版本與 version 匹配,則為 1,否則為 0

$<Fortran_COMPILER_VERSION>

使用的 Fortran 編譯器版本。

$<Fortran_COMPILER_VERSION:version>

如果 Fortran 編譯器的版本與 version 匹配,則為 1,否則為 0

$<HIP_COMPILER_VERSION>

在版本 3.21 中新增。

使用的 HIP 編譯器版本。

$<HIP_COMPILER_VERSION:version>

在版本 3.21 中新增。

如果 HIP 編譯器的版本與 version 匹配,則為 1,否則為 0

$<ISPC_COMPILER_VERSION>

在版本 3.19 中新增。

使用的 ISPC 編譯器版本。

$<ISPC_COMPILER_VERSION:version>

在版本 3.19 中新增。

如果 ISPC 編譯器的版本與 version 匹配,則為 1,否則為 0

編譯器語言、ID 和前端變體

另請參閱 CMAKE_<LANG>_COMPILER_IDCMAKE_<LANG>_COMPILER_FRONTEND_VARIANT 變數,它們與本小節中的大多數表達式密切相關。

$<C_COMPILER_ID>

CMake 所使用的 C 編譯器的編譯器 ID。

$<C_COMPILER_ID:compiler_ids>

其中 compiler_ids 是一個逗號分隔的列表。如果 CMake 所使用的 C 編譯器的編譯器 ID 符合 compiler_ids 中的任何一個項目,則為 1,否則為 0

變更於 3.15 版本: 可以指定多個 compiler_ids。 CMake 3.14 及更早版本僅接受單個編譯器 ID。

$<CXX_COMPILER_ID>

CMake 所使用的 C++ 編譯器的編譯器 ID。

$<CXX_COMPILER_ID:compiler_ids>

其中 compiler_ids 是一個逗號分隔的列表。如果 CMake 所使用的 C++ 編譯器的編譯器 ID 符合 compiler_ids 中的任何一個項目,則為 1,否則為 0

變更於 3.15 版本: 可以指定多個 compiler_ids。 CMake 3.14 及更早版本僅接受單個編譯器 ID。

$<CUDA_COMPILER_ID>

在版本 3.15 中新增。

CMake 所使用的 CUDA 編譯器的編譯器 ID。

$<CUDA_COMPILER_ID:compiler_ids>

在版本 3.15 中新增。

其中 compiler_ids 是一個逗號分隔的列表。如果 CMake 所使用的 CUDA 編譯器的編譯器 ID 符合 compiler_ids 中的任何一個項目,則為 1,否則為 0

$<OBJC_COMPILER_ID>

在版本 3.16 中新增。

CMake 所使用的 Objective-C 編譯器的編譯器 ID。

$<OBJC_COMPILER_ID:compiler_ids>

在版本 3.16 中新增。

其中 compiler_ids 是一個逗號分隔的列表。如果 CMake 所使用的 Objective-C 編譯器的編譯器 ID 符合 compiler_ids 中的任何一個項目,則為 1,否則為 0

$<OBJCXX_COMPILER_ID>

在版本 3.16 中新增。

CMake 所使用的 Objective-C++ 編譯器的編譯器 ID。

$<OBJCXX_COMPILER_ID:compiler_ids>

在版本 3.16 中新增。

其中 compiler_ids 是一個逗號分隔的列表。如果 CMake 所使用的 Objective-C++ 編譯器的編譯器 ID 符合 compiler_ids 中的任何一個項目,則為 1,否則為 0

$<Fortran_COMPILER_ID>

CMake 所使用的 Fortran 編譯器的編譯器 ID。

$<Fortran_COMPILER_ID:compiler_ids>

其中 compiler_ids 是一個逗號分隔的列表。如果 CMake 所使用的 Fortran 編譯器的編譯器 ID 符合 compiler_ids 中的任何一個項目,則為 1,否則為 0

變更於 3.15 版本: 可以指定多個 compiler_ids。 CMake 3.14 及更早版本僅接受單個編譯器 ID。

$<HIP_COMPILER_ID>

在版本 3.21 中新增。

CMake 所使用的 HIP 編譯器的編譯器 ID。

$<HIP_COMPILER_ID:compiler_ids>

在版本 3.21 中新增。

其中 compiler_ids 是一個逗號分隔的列表。如果 CMake 所使用的 HIP 編譯器的編譯器 ID 符合 compiler_ids 中的任何一個項目,則為 1,否則為 0

$<ISPC_COMPILER_ID>

在版本 3.19 中新增。

CMake 所使用的 ISPC 編譯器的編譯器 ID。

$<ISPC_COMPILER_ID:compiler_ids>

在版本 3.19 中新增。

其中 compiler_ids 是一個逗號分隔的列表。如果 CMake 所使用的 ISPC 編譯器的編譯器 ID 符合 compiler_ids 中的任何一個項目,則為 1,否則為 0

$<C_COMPILER_FRONTEND_VARIANT>

版本 3.30 新增。

CMake 所使用的 C 編譯器的編譯器前端變體。

$<C_COMPILER_FRONTEND_VARIANT:compiler_ids>

版本 3.30 新增。

其中 compiler_ids 是一個逗號分隔的列表。如果 CMake 所使用的 C 編譯器的編譯器前端變體符合 compiler_ids 中的任何一個項目,則為 1,否則為 0

$<CXX_COMPILER_FRONTEND_VARIANT>

版本 3.30 新增。

CMake 所使用的 C++ 編譯器的編譯器前端變體。

$<CXX_COMPILER_FRONTEND_VARIANT:compiler_ids>

版本 3.30 新增。

其中 compiler_ids 是一個逗號分隔的列表。如果 CMake 所使用的 C++ 編譯器的編譯器前端變體符合 compiler_ids 中的任何一個項目,則為 1,否則為 0

$<CUDA_COMPILER_FRONTEND_VARIANT>

版本 3.30 新增。

CMake 所使用的 CUDA 編譯器的編譯器 ID。

$<CUDA_COMPILER_FRONTEND_VARIANT:compiler_ids>

版本 3.30 新增。

其中 compiler_ids 是一個逗號分隔的列表。如果 CMake 所使用的 CUDA 編譯器的編譯器前端變體符合 compiler_ids 中的任何一個項目,則為 1,否則為 0

$<OBJC_COMPILER_FRONTEND_VARIANT>

版本 3.30 新增。

CMake 所使用的 Objective-C 編譯器的編譯器前端變體。

$<OBJC_COMPILER_FRONTEND_VARIANT:compiler_ids>

版本 3.30 新增。

其中 compiler_ids 是一個逗號分隔的列表。如果 CMake 所使用的 Objective-C 編譯器的編譯器前端變體符合 compiler_ids 中的任何一個項目,則為 1,否則為 0

$<OBJCXX_COMPILER_FRONTEND_VARIANT>

版本 3.30 新增。

CMake 所使用的 Objective-C++ 編譯器的編譯器前端變體。

$<OBJCXX_COMPILER_FRONTEND_VARIANT:compiler_ids>

版本 3.30 新增。

其中 compiler_ids 是一個逗號分隔的列表。如果 CMake 所使用的 Objective-C++ 編譯器的編譯器前端變體符合 compiler_ids 中的任何一個項目,則為 1,否則為 0

$<Fortran_COMPILER_FRONTEND_VARIANT>

版本 3.30 新增。

CMake 所使用的 Fortran 編譯器的編譯器 ID。

$<Fortran_COMPILER_FRONTEND_VARIANT:compiler_ids>

版本 3.30 新增。

其中 compiler_ids 是一個逗號分隔的列表。如果 CMake 所使用的 Fortran 編譯器的編譯器前端變體符合 compiler_ids 中的任何一個項目,則為 1,否則為 0

$<HIP_COMPILER_FRONTEND_VARIANT>

版本 3.30 新增。

CMake 所使用的 HIP 編譯器的編譯器 ID。

$<HIP_COMPILER_FRONTEND_VARIANT:compiler_ids>

版本 3.30 新增。

其中 compiler_ids 是一個逗號分隔的列表。如果 CMake 所使用的 HIP 編譯器的編譯器前端變體符合 compiler_ids 中的任何一個項目,則為 1,否則為 0

$<ISPC_COMPILER_FRONTEND_VARIANT>

版本 3.30 新增。

CMake 所使用的 ISPC 編譯器的編譯器 ID。

$<ISPC_COMPILER_FRONTEND_VARIANT:compiler_ids>

版本 3.30 新增。

其中 compiler_ids 是一個逗號分隔的列表。如果 CMake 所使用的 ISPC 編譯器的編譯器前端變體符合 compiler_ids 中的任何一個項目,則為 1,否則為 0

$<COMPILE_LANGUAGE>

版本 3.3 新增。

評估編譯選項時,原始檔的編譯語言。 參見相關的布林表示式 $<COMPILE_LANGUAGE:language>,以了解關於此產生器表達式的可移植性的注意事項。

$<COMPILE_LANGUAGE:languages>

版本 3.3 新增。

變更於 3.15 版本: 可以為 languages 指定多種語言。 CMake 3.14 及更早版本僅接受單一語言。

1 當用於編譯單元的語言符合 languages 中任何逗號分隔的項目時,否則為 0。 此表達式可用於為目標中特定語言的原始檔指定編譯選項、編譯定義和包含目錄。 例如

add_executable(myapp main.cpp foo.c bar.cpp zot.cu)
target_compile_options(myapp
  PRIVATE $<$<COMPILE_LANGUAGE:CXX>:-fno-exceptions>
)
target_compile_definitions(myapp
  PRIVATE $<$<COMPILE_LANGUAGE:CXX>:COMPILING_CXX>
          $<$<COMPILE_LANGUAGE:CUDA>:COMPILING_CUDA>
)
target_include_directories(myapp
  PRIVATE $<$<COMPILE_LANGUAGE:CXX,CUDA>:/opt/foo/headers>
)

這指定僅針對 C++ 使用 -fno-exceptions 編譯選項、COMPILING_CXX 編譯定義,以及 cxx_headers 包含目錄(省略了編譯器 ID 檢查)。 它還為 CUDA 指定了 COMPILING_CUDA 編譯定義。

請注意,使用 Visual Studio 產生器Xcode,無法針對 CCXX 語言分別表示目標範圍的編譯定義或包含目錄。 此外,使用 Visual Studio 產生器,也無法針對 CCXX 語言分別表示目標範圍的旗標。 在這些產生器下,如果存在任何 C++ 原始檔,則 C 和 C++ 原始檔的表達式都將使用 CXX 進行評估,否則使用 C。 一種解決方法是為每種原始檔語言建立單獨的程式庫

add_library(myapp_c foo.c)
add_library(myapp_cxx bar.cpp)
target_compile_options(myapp_cxx PUBLIC -fno-exceptions)
add_executable(myapp main.cpp)
target_link_libraries(myapp myapp_c myapp_cxx)
$<COMPILE_LANG_AND_ID:language,compiler_ids>

在版本 3.15 中新增。

1 當用於編譯單元的語言符合 language 且 CMake 的 language 編譯器的編譯器 ID 符合 compiler_ids 中任何逗號分隔的項目時,否則為 0。 此表達式是 $<COMPILE_LANGUAGE:language>$<LANG_COMPILER_ID:compiler_ids> 組合的簡短形式。 此表達式可用於為目標中特定語言和編譯器組合的原始檔指定編譯選項、編譯定義和包含目錄。 例如

add_executable(myapp main.cpp foo.c bar.cpp zot.cu)
target_compile_definitions(myapp
  PRIVATE $<$<COMPILE_LANG_AND_ID:CXX,AppleClang,Clang>:COMPILING_CXX_WITH_CLANG>
          $<$<COMPILE_LANG_AND_ID:CXX,Intel>:COMPILING_CXX_WITH_INTEL>
          $<$<COMPILE_LANG_AND_ID:C,Clang>:COMPILING_C_WITH_CLANG>
)

這指定了基於編譯器 ID 和編譯語言的不同編譯定義的使用。 當 Clang 是 CXX 編譯器時,此範例將具有 COMPILING_CXX_WITH_CLANG 編譯定義,而當 Intel 是 CXX 編譯器時,則具有 COMPILING_CXX_WITH_INTEL。 同樣地,當 C 編譯器是 Clang 時,它只會看到 COMPILING_C_WITH_CLANG 定義。

如果沒有 COMPILE_LANG_AND_ID 產生器表達式,相同的邏輯將表示為

target_compile_definitions(myapp
  PRIVATE $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CXX_COMPILER_ID:AppleClang,Clang>>:COMPILING_CXX_WITH_CLANG>
          $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CXX_COMPILER_ID:Intel>>:COMPILING_CXX_WITH_INTEL>
          $<$<AND:$<COMPILE_LANGUAGE:C>,$<C_COMPILER_ID:Clang>>:COMPILING_C_WITH_CLANG>
)

編譯功能

$<COMPILE_FEATURES:features>

版本 3.1 新增。

其中 features 是一個逗號分隔的列表。 如果 'head' 目標可以使用所有 features,則評估結果為 1,否則為 0。 如果在評估目標的連結實作時使用此表達式,並且任何依賴關係遞移地增加了 'head' 目標所需的 C_STANDARDCXX_STANDARD,則會報告錯誤。 請參閱 cmake-compile-features(7) 手冊,以取得有關編譯功能的資訊和支援的編譯器列表。

編譯上下文

$<COMPILE_ONLY:...>

在版本 3.27 中新增。

當收集遞移編譯屬性時,... 的內容,否則為空字串。 這旨在用於 INTERFACE_LINK_LIBRARIESLINK_LIBRARIES 目標屬性中,通常透過 target_link_libraries() 命令填入。 提供編譯使用需求,而沒有任何連結需求。

使用案例包括僅標頭檔的使用,其中已知所有使用方式都沒有連結需求(例如,所有 inline 或 C++ 模板程式庫)。

請注意,要正確評估此表達式,需要將策略 CMP0099 設定為 NEW

連結器語言和 ID

版本 3.18 新增。

評估連結選項時,目標的連結語言。 參見相關的布林表示式 $<LINK_LANGUAGE:languages>,以了解關於此產生器表達式的可移植性的注意事項。

注意

連結程式庫屬性不支援此產生器表達式,以避免由於這些屬性的雙重評估而造成的副作用。

版本 3.18 新增。

1 當用於連結步驟的語言符合 language 且 CMake 的語言連結器的編譯器 ID 符合 compiler_ids 中任何逗號分隔的項目時,否則為 0。 此表達式是 $<LINK_LANGUAGE:language>$<LANG_COMPILER_ID:compiler_ids> 組合的簡短形式。 此表達式可用於為目標中特定語言和連結器組合指定連結程式庫、連結選項、連結目錄和連結依賴項。 例如

add_library(libC_Clang ...)
add_library(libCXX_Clang ...)
add_library(libC_Intel ...)
add_library(libCXX_Intel ...)

add_executable(myapp main.c)
if (CXX_CONFIG)
  target_sources(myapp PRIVATE file.cxx)
endif()
target_link_libraries(myapp
  PRIVATE $<$<LINK_LANG_AND_ID:CXX,Clang,AppleClang>:libCXX_Clang>
          $<$<LINK_LANG_AND_ID:C,Clang,AppleClang>:libC_Clang>
          $<$<LINK_LANG_AND_ID:CXX,Intel>:libCXX_Intel>
          $<$<LINK_LANG_AND_ID:C,Intel>:libC_Intel>)

這指定了基於編譯器 ID 和連結語言的不同連結程式庫的使用。 當 ClangAppleClangCXX 連結器時,此範例將具有目標 libCXX_Clang 作為連結依賴項,而當 IntelCXX 連結器時,則具有 libCXX_Intel。 同樣地,當 C 連結器是 ClangAppleClang 時,將新增目標 libC_Clang 作為連結依賴項,而當 IntelC 連結器時,則新增 libC_Intel

請參閱 $<LINK_LANGUAGE:language> 相關的注意事項,以了解有關此產生器表達式的使用限制。

目標依賴表示式

目標元數據

這些表示式查詢關於目標的資訊。

$<TARGET_EXISTS:tgt>

在版本 3.12 中新增。

如果 tgt 作為 CMake 目標存在,則為 1,否則為 0

$<TARGET_NAME_IF_EXISTS:tgt>

在版本 3.12 中新增。

如果目標存在,則為目標名稱 tgt,否則為空字串。

請注意,tgt 不會新增為評估此表示式的目標的依賴項。

$<TARGET_NAME:tgt>

寫入的目標名稱 tgt。這將 tgt 標記為較大表示式內目標的名稱,如果將目標匯出到多個相依匯出集中,則這是必需的。tgt 文字必須是目標的文字名稱;它可能不包含產生器表示式。目標不必存在。

$<TARGET_POLICY:policy>

如果建立「head」目標時 policyNEW,則為 1,否則為 0。如果未設定 policy,則將發出策略的警告訊息。此產生器表示式僅適用於部分策略。

目標屬性

這些表示式查詢 目標屬性 的值。

$<TARGET_PROPERTY:tgt,prop>

目標 tgt 上屬性 prop 的值,如果未設定屬性,則為空。

請注意,tgt 不會新增為評估此表示式的目標的依賴項。

版本 3.26 變更: 目標使用需求 的評估期間遇到時,通常在 INTERFACE_* 目標屬性中,tgt 名稱的查詢發生在指定需求的目標目錄中,而不是表達式正在評估的消耗目標的目錄中。

$<TARGET_PROPERTY:prop>

表達式正在評估的目標上屬性 prop 的值,如果未設定屬性,則為空。請注意,對於 目標使用需求 中的產生器表示式,這是消耗目標,而不是指定需求的目標。

這些表示式對於某些屬性具有特殊的評估規則

目標建置規格屬性

這些評估為 分號分隔列表,表示目標本身的值與目標的 LINK_LIBRARIES 指定的目標上對應的 目標使用需求 值的聯集

LINK_LIBRARIES 本身的評估不是可遞移的。

目標使用需求屬性

這些評估為 分號分隔列表,表示目標本身的值與目標的 INTERFACE_LINK_LIBRARIES 指定的目標上相同屬性的值的聯集

INTERFACE_LINK_LIBRARIES 本身的評估不是可遞移的。

自訂遞移屬性

版本 3.30 新增。

這些在評估期間按如下方式處理

如果 PROP 同時由 TRANSITIVE_COMPILE_PROPERTIESTRANSITIVE_LINK_PROPERTIES 命名,則後者優先。

相容介面屬性

這些屬性的評估結果為單一值,該值結合了目標本身、目標的 LINK_LIBRARIES 所命名的目標,以及連結目標的 INTERFACE_LINK_LIBRARIES 的遞移閉包。來自多個目標的相容介面屬性的值,會根據定義它的 COMPATIBLE_INTERFACE_* 屬性所需相容性的類型進行組合。

目標產出物

這些表達式查詢與給定目標 tgt 相關聯的產出物的資訊。除非另有說明,否則這可以是任何執行時期產出物,即:

在下文中,「tgt 檔名」一詞是指 tgt 二進制檔案的名稱。這必須與「目標名稱」一詞區分開來,後者僅僅是字串 tgt

$<TARGET_FILE:tgt>

指向 tgt 二進制檔案的完整路徑。

請注意,除非表達式用於 add_custom_command()add_custom_target() 中,否則 tgt 不會作為評估此表達式的目標的依賴項新增。

$<TARGET_FILE_BASE_NAME:tgt>

在版本 3.15 中新增。

tgt 的基礎名稱,即沒有前綴詞和後綴詞的 $<TARGET_FILE_NAME:tgt>。例如,如果 tgt 檔名為 libbase.so,則基礎名稱為 base

另請參閱 OUTPUT_NAMEARCHIVE_OUTPUT_NAMELIBRARY_OUTPUT_NAMERUNTIME_OUTPUT_NAME 目標屬性,以及它們的組態特定變體 OUTPUT_NAME_<CONFIG>ARCHIVE_OUTPUT_NAME_<CONFIG>LIBRARY_OUTPUT_NAME_<CONFIG>RUNTIME_OUTPUT_NAME_<CONFIG>

也可以考慮 <CONFIG>_POSTFIXDEBUG_POSTFIX 目標屬性。

請注意,tgt 不會新增為評估此表示式的目標的依賴項。

$<TARGET_FILE_PREFIX:tgt>

在版本 3.15 中新增。

tgt 檔名的前綴詞 (例如 lib)。

另請參閱 PREFIX 目標屬性。

請注意,tgt 不會新增為評估此表示式的目標的依賴項。

$<TARGET_FILE_SUFFIX:tgt>

在版本 3.15 中新增。

tgt 檔名的後綴詞 (副檔名,例如 .so.exe)。

另請參閱 SUFFIX 目標屬性。

請注意,tgt 不會新增為評估此表示式的目標的依賴項。

$<TARGET_FILE_NAME:tgt>

tgt 檔名。

請注意,tgt 不會作為評估此表達式的目標的依賴項新增 (請參閱策略 CMP0112)。

$<TARGET_FILE_DIR:tgt>

tgt 二進制檔案的目錄。

請注意,tgt 不會作為評估此表達式的目標的依賴項新增 (請參閱策略 CMP0112)。

$<TARGET_IMPORT_FILE:tgt>

在版本 3.27 中新增。

連結器匯入檔案的完整路徑。在 DLL 平台上,這將是 .lib 檔案。對於 AIX 上的可執行檔,以及 macOS 上的共享函式庫,根據 ENABLE_EXPORTS 屬性的值,它可能是 .imp.tbd 匯入檔案。

當沒有與目標關聯的匯入檔案時,此項會展開為空字串。

$<TARGET_IMPORT_FILE_BASE_NAME:tgt>

在版本 3.27 中新增。

目標 tgt 的連結器匯入檔案的基礎名稱,不含前綴詞或後綴詞。例如,如果目標檔名為 libbase.tbd,則基礎名稱為 base

另請參閱 OUTPUT_NAMEARCHIVE_OUTPUT_NAME 目標屬性,以及它們的組態特定變體 OUTPUT_NAME_<CONFIG>ARCHIVE_OUTPUT_NAME_<CONFIG>

也可以考慮 <CONFIG>_POSTFIXDEBUG_POSTFIX 目標屬性。

請注意,tgt 不會新增為評估此表示式的目標的依賴項。

$<TARGET_IMPORT_FILE_PREFIX:tgt>

在版本 3.27 中新增。

目標 tgt 的匯入檔案的前綴詞。

另請參閱 IMPORT_PREFIX 目標屬性。

請注意,tgt 不會新增為評估此表示式的目標的依賴項。

$<TARGET_IMPORT_FILE_SUFFIX:tgt>

在版本 3.27 中新增。

目標 tgt 的匯入檔案的後綴詞。

後綴詞對應於檔案副檔名 (例如 .lib.tbd)。

另請參閱 IMPORT_SUFFIX 目標屬性。

請注意,tgt 不會新增為評估此表示式的目標的依賴項。

$<TARGET_IMPORT_FILE_NAME:tgt>

在版本 3.27 中新增。

目標 tgt 的匯入檔案的名稱。

請注意,tgt 不會新增為評估此表示式的目標的依賴項。

$<TARGET_IMPORT_FILE_DIR:tgt>

在版本 3.27 中新增。

目標 tgt 的匯入檔案的目錄。

請注意,tgt 不會新增為評估此表示式的目標的依賴項。

$<TARGET_LINKER_FILE:tgt>

連結到 tgt 目標時使用的檔案。這通常會是 tgt 所代表的函式庫 (.a.lib.so),但對於 DLL 平台上的共享函式庫,它將是與 DLL 關聯的 .lib 匯入函式庫。

版本 3.27 新增: 在 macOS 上,根據 ENABLE_EXPORTS 屬性的值,它可能是與共享函式庫關聯的 .tbd 匯入檔案。

此產生器表達式等效於 $<TARGET_LINKER_LIBRARY_FILE>$<TARGET_LINKER_IMPORT_FILE> 產生器表達式,具體取決於目標和平台的特性。

$<TARGET_LINKER_FILE_BASE_NAME:tgt>

在版本 3.15 中新增。

用於連結目標 tgt 的檔案的基礎名稱,即沒有前綴詞和後綴詞的 $<TARGET_LINKER_FILE_NAME:tgt>。例如,如果目標檔名為 libbase.a,則基礎名稱為 base

另請參閱 OUTPUT_NAMEARCHIVE_OUTPUT_NAMELIBRARY_OUTPUT_NAME 目標屬性,以及它們的組態特定變體 OUTPUT_NAME_<CONFIG>ARCHIVE_OUTPUT_NAME_<CONFIG>LIBRARY_OUTPUT_NAME_<CONFIG>

也可以考慮 <CONFIG>_POSTFIXDEBUG_POSTFIX 目標屬性。

請注意,tgt 不會新增為評估此表示式的目標的依賴項。

$<TARGET_LINKER_FILE_PREFIX:tgt>

在版本 3.15 中新增。

用於連結目標 tgt 的檔案的前綴詞。

另請參閱 PREFIXIMPORT_PREFIX 目標屬性。

請注意,tgt 不會新增為評估此表示式的目標的依賴項。

$<TARGET_LINKER_FILE_SUFFIX:tgt>

在版本 3.15 中新增。

用於連結的檔案的後綴詞,其中 tgt 是目標的名稱。

後綴詞對應於檔案副檔名 (例如 ".so" 或 ".lib")。

另請參閱 SUFFIXIMPORT_SUFFIX 目標屬性。

請注意,tgt 不會新增為評估此表示式的目標的依賴項。

$<TARGET_LINKER_FILE_NAME:tgt>

用於連結目標 tgt 的檔案的名稱。

請注意,tgt 不會作為評估此表達式的目標的依賴項新增 (請參閱策略 CMP0112)。

$<TARGET_LINKER_FILE_DIR:tgt>

用於連結目標 tgt 的檔案的目錄。

請注意,tgt 不會作為評估此表達式的目標的依賴項新增 (請參閱策略 CMP0112)。

$<TARGET_LINKER_LIBRARY_FILE:tgt>

在版本 3.27 中新增。

當使用直接函式庫而不是匯入檔案連結到 tgt 目標時,使用的檔案。這通常會是 tgt 所代表的函式庫 (.a.so.dylib)。因此,在 DLL 平台上,它將會是空字串。

$<TARGET_LINKER_LIBRARY_FILE_BASE_NAME:tgt>

在版本 3.27 中新增。

用於連結目標 tgt 的函式庫檔案的基礎名稱,即沒有前綴詞和後綴詞的 $<TARGET_LINKER_LIBRARY_FILE_NAME:tgt>。例如,如果目標檔名為 libbase.a,則基礎名稱為 base

另請參閱 OUTPUT_NAMEARCHIVE_OUTPUT_NAMELIBRARY_OUTPUT_NAME 目標屬性,以及它們的組態特定變體 OUTPUT_NAME_<CONFIG>ARCHIVE_OUTPUT_NAME_<CONFIG>LIBRARY_OUTPUT_NAME_<CONFIG>

也可以考慮 <CONFIG>_POSTFIXDEBUG_POSTFIX 目標屬性。

請注意,tgt 不會新增為評估此表示式的目標的依賴項。

$<TARGET_LINKER_LIBRARY_FILE_PREFIX:tgt>

在版本 3.27 中新增。

用於連結目標 tgt 的函式庫檔案的前綴詞。

另請參閱 PREFIX 目標屬性。

請注意,tgt 不會新增為評估此表示式的目標的依賴項。

$<TARGET_LINKER_LIBRARY_FILE_SUFFIX:tgt>

在版本 3.27 中新增。

用於連結目標 tgt 的函式庫檔案的後綴詞。

後綴詞對應於檔案副檔名 (例如 ".a" 或 ".dylib")。

另請參閱 SUFFIX 目標屬性。

請注意,tgt 不會新增為評估此表示式的目標的依賴項。

$<TARGET_LINKER_LIBRARY_FILE_NAME:tgt>

在版本 3.27 中新增。

用於連結目標 tgt 的函式庫檔案的名稱。

請注意,tgt 不會新增為評估此表示式的目標的依賴項。

$<TARGET_LINKER_LIBRARY_FILE_DIR:tgt>

在版本 3.27 中新增。

用於連結目標 tgt 的函式庫檔案的目錄。

請注意,tgt 不會新增為評估此表示式的目標的依賴項。

$<TARGET_LINKER_IMPORT_FILE:tgt>

在版本 3.27 中新增。

當連結到 tgt 目標時,會使用匯入檔。這通常會是 tgt 所代表的匯入檔 (例如 .lib.tbd)。因此,當連結步驟中未涉及匯入檔時,將會傳回空字串。

$<TARGET_LINKER_IMPORT_FILE_BASE_NAME:tgt>

在版本 3.27 中新增。

用於連結目標 tgt 的匯入檔的基底名稱,即 $<TARGET_LINKER_IMPORT_FILE_NAME:tgt>,不包含前綴詞和後綴詞。例如,如果目標檔名為 libbase.tbd,則基底名稱為 base

另請參閱 OUTPUT_NAMEARCHIVE_OUTPUT_NAME 目標屬性,以及它們的組態特定變體 OUTPUT_NAME_<CONFIG>ARCHIVE_OUTPUT_NAME_<CONFIG>

<CONFIG>_POSTFIXDEBUG_POSTFIX 目標屬性也應考慮在內。

請注意,tgt 不會新增為評估此表示式的目標的依賴項。

$<TARGET_LINKER_IMPORT_FILE_PREFIX:tgt>

在版本 3.27 中新增。

用於連結目標 tgt 的匯入檔的前綴詞。

另請參閱 IMPORT_PREFIX 目標屬性。

請注意,tgt 不會新增為評估此表示式的目標的依賴項。

$<TARGET_LINKER_IMPORT_FILE_SUFFIX:tgt>

在版本 3.27 中新增。

用於連結目標 tgt 的匯入檔的後綴詞。

後綴詞對應於檔案副檔名 (例如 ".lib" 或 ".tbd")。

另請參閱 IMPORT_SUFFIX 目標屬性。

請注意,tgt 不會新增為評估此表示式的目標的依賴項。

$<TARGET_LINKER_IMPORT_FILE_NAME:tgt>

在版本 3.27 中新增。

用於連結目標 tgt 的匯入檔的名稱。

請注意,tgt 不會新增為評估此表示式的目標的依賴項。

$<TARGET_LINKER_IMPORT_FILE_DIR:tgt>

在版本 3.27 中新增。

用於連結目標 tgt 的匯入檔的目錄。

請注意,tgt 不會新增為評估此表示式的目標的依賴項。

$<TARGET_SONAME_FILE:tgt>

具有 soname (.so.3) 的檔案,其中 tgt 是目標的名稱。

$<TARGET_SONAME_FILE_NAME:tgt>

具有 soname (.so.3) 的檔案名稱。

請注意,tgt 不會新增為評估此表達式的目標的相依性 (請參閱政策 CMP0112)。

$<TARGET_SONAME_FILE_DIR:tgt>

具有 soname (.so.3) 的檔案目錄。

請注意,tgt 不會新增為評估此表達式的目標的相依性 (請參閱政策 CMP0112)。

$<TARGET_SONAME_IMPORT_FILE:tgt>

在版本 3.27 中新增。

具有 soname (.3.tbd) 的匯入檔,其中 tgt 是目標的名稱。

$<TARGET_SONAME_IMPORT_FILE_NAME:tgt>

在版本 3.27 中新增。

具有 soname (.3.tbd) 的匯入檔名稱。

請注意,tgt 不會新增為評估此表示式的目標的依賴項。

$<TARGET_SONAME_IMPORT_FILE_DIR:tgt>

在版本 3.27 中新增。

具有 soname (.3.tbd) 的匯入檔目錄。

請注意,tgt 不會新增為評估此表示式的目標的依賴項。

$<TARGET_PDB_FILE:tgt>

版本 3.1 新增。

連結器產生的程式資料庫檔案 (.pdb) 的完整路徑,其中 tgt 是目標的名稱。

另請參閱 PDB_NAMEPDB_OUTPUT_DIRECTORY 目標屬性,以及它們的組態特定變體 PDB_NAME_<CONFIG>PDB_OUTPUT_DIRECTORY_<CONFIG>

$<TARGET_PDB_FILE_BASE_NAME:tgt>

在版本 3.15 中新增。

連結器產生的程式資料庫檔案 (.pdb) 的基底名稱,其中 tgt 是目標的名稱。

基底名稱對應於目標 PDB 檔名 (請參閱 $<TARGET_PDB_FILE_NAME:tgt>),不包含前綴詞和後綴詞。例如,如果目標檔名為 base.pdb,則基底名稱為 base

另請參閱 PDB_NAME 目標屬性及其組態特定變體 PDB_NAME_<CONFIG>

<CONFIG>_POSTFIXDEBUG_POSTFIX 目標屬性也應考慮在內。

請注意,tgt 不會新增為評估此表示式的目標的依賴項。

$<TARGET_PDB_FILE_NAME:tgt>

版本 3.1 新增。

連結器產生的程式資料庫檔案 (.pdb) 的名稱。

請注意,tgt 不會新增為評估此表達式的目標的相依性 (請參閱政策 CMP0112)。

$<TARGET_PDB_FILE_DIR:tgt>

版本 3.1 新增。

連結器產生的程式資料庫檔案 (.pdb) 的目錄。

請注意,tgt 不會新增為評估此表達式的目標的相依性 (請參閱政策 CMP0112)。

$<TARGET_BUNDLE_DIR:tgt>

在版本 3.9 中新增。

套件目錄的完整路徑 (/path/to/my.app/path/to/my.framework/path/to/my.bundle),其中 tgt 是目標的名稱。

請注意,tgt 不會新增為評估此表達式的目標的相依性 (請參閱政策 CMP0112)。

$<TARGET_BUNDLE_DIR_NAME:tgt>

在版本 3.24 中新增。

套件目錄的名稱 (my.appmy.frameworkmy.bundle),其中 tgt 是目標的名稱。

請注意,tgt 不會新增為評估此表達式的目標的相依性 (請參閱政策 CMP0112)。

$<TARGET_BUNDLE_CONTENT_DIR:tgt>

在版本 3.9 中新增。

套件內容目錄的完整路徑,其中 tgt 是目標的名稱。對於 macOS SDK,它會指向 /path/to/my.app/Contents/path/to/my.framework/path/to/my.bundle/Contents。對於所有其他 SDK (例如 iOS),由於扁平的套件結構,它會指向 /path/to/my.app/path/to/my.framework/path/to/my.bundle

請注意,tgt 不會新增為評估此表達式的目標的相依性 (請參閱政策 CMP0112)。

$<TARGET_OBJECTS:tgt>

版本 3.1 新增。

建置 tgt 所產生的物件清單。這通常用於 物件程式庫 目標。

$<TARGET_RUNTIME_DLLS:tgt>

在版本 3.21 中新增。

目標在執行階段相依的 DLL 清單。這由目標的遞移相依性中所有 SHARED 目標的位置決定。如果只需要 DLL 的目錄,請參閱 TARGET_RUNTIME_DLL_DIRS 產生器表達式。在可執行檔、SHARED 程式庫和 MODULE 程式庫以外的目標上使用此產生器表達式是錯誤的。在非 DLL 平台上,此表達式始終評估為空字串

此產生器表達式可用於使用 cmake -E copy -t 命令在 POST_BUILD 自訂命令中將目標相依的所有 DLL 複製到其輸出目錄中。例如

find_package(foo CONFIG REQUIRED) # package generated by install(EXPORT)

add_executable(exe main.c)
target_link_libraries(exe PRIVATE foo::foo foo::bar)
add_custom_command(TARGET exe POST_BUILD
  COMMAND ${CMAKE_COMMAND} -E copy -t $<TARGET_FILE_DIR:exe> $<TARGET_RUNTIME_DLLS:exe>
  COMMAND_EXPAND_LISTS
)

注意

匯入目標 僅在它們知道其 .dll 檔案的位置時才受支援。匯入的 SHARED 程式庫必須將 IMPORTED_LOCATION 設定為其 .dll 檔案。請參閱 add_library 匯入程式庫 區段以取得詳細資訊。許多 Find Modules 產生具有 UNKNOWN 類型的匯入目標,因此將被忽略。

在支援執行階段路徑 (RPATH) 的平台上,請參閱 INSTALL_RPATH 目標屬性。在 Apple 平台上,請參閱 INSTALL_NAME_DIR 目標屬性。

$<TARGET_RUNTIME_DLL_DIRS:tgt>

在版本 3.27 中新增。

包含目標在執行階段相依的 DLL 的目錄清單 (請參閱 TARGET_RUNTIME_DLLS)。這由目標的遞移相依性中所有 SHARED 目標的位置決定。在可執行檔、SHARED 程式庫和 MODULE 程式庫以外的目標上使用此產生器表達式是錯誤的。在非 DLL 平台上,此表達式始終評估為空字串

此產生器表達式可以例如用於使用 file(GENERATE) 建立批次檔,該批次檔會相應地設定 PATH 環境變數。

匯出和安裝表達式

$<INSTALL_INTERFACE:...>

當使用 install(EXPORT) 匯出屬性時,... 的內容,否則為空。

$<BUILD_INTERFACE:...>

當使用 export() 匯出屬性時,或當目標被同一個建置系統中的另一個目標使用時,... 的內容。否則展開為空字串。

$<BUILD_LOCAL_INTERFACE:...>

在版本 3.26 中新增。

當目標被同一個建置系統中的另一個目標使用時,... 的內容。否則展開為空字串。

$<INSTALL_PREFIX>

當目標透過 install(EXPORT) 匯出時,或在 INSTALL_NAME_DIR 屬性或 install(RUNTIME_DEPENDENCY_SET)INSTALL_NAME_DIR 參數中評估時,安裝前綴詞的內容,否則為空。

在版本 3.27 中變更:install(CODE) 的 code 參數或 install(SCRIPT) 的 file 參數中評估為安裝前綴詞的內容。

多層級表達式評估

$<GENEX_EVAL:expr>

在版本 3.12 中新增。

在目前上下文中評估為產生器表達式的 expr 的內容。這使得能夠使用其評估結果本身為產生器表達式的產生器表達式。

$<TARGET_GENEX_EVAL:tgt,expr>

在版本 3.12 中新增。

tgt 目標的上下文中評估為產生器表達式的 expr 的內容。這使得能夠使用本身包含產生器表達式的自訂目標屬性。

當您想要管理支援產生器表達式的自訂屬性時,評估產生器表達式的功能非常有用。例如

add_library(foo ...)

set_property(TARGET foo PROPERTY
  CUSTOM_KEYS $<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS>
)

add_custom_target(printFooKeys
  COMMAND ${CMAKE_COMMAND} -E echo $<TARGET_PROPERTY:foo,CUSTOM_KEYS>
)

printFooKeys 自訂命令的簡單實作是錯誤的,因為 CUSTOM_KEYS 目標屬性未評估,並且內容按原樣傳遞 (即 $<$<CONFIG:DEBUG>:FOO_EXTRA_THINGS>)。

為了獲得預期的結果 (即如果組態為 Debug,則為 FOO_EXTRA_THINGS),需要評估 $<TARGET_PROPERTY:foo,CUSTOM_KEYS> 的輸出

add_custom_target(printFooKeys
  COMMAND ${CMAKE_COMMAND} -E
    echo $<TARGET_GENEX_EVAL:foo,$<TARGET_PROPERTY:foo,CUSTOM_KEYS>>
)

逸出字元

這些表達式評估為特定的字串文字。在您需要防止它們具有特殊含義的情況下,使用它們代替實際的字串文字。

$<ANGLE-R>

文字 >。例如,用於比較包含 > 的字串。

$<COMMA>

文字 ,。例如,用於比較包含 , 的字串。

$<SEMICOLON>

文字 ;。用於防止對帶有 ; 的引數進行列表展開。

$<QUOTE>

版本 3.30 新增。

文字 "。用於允許產生器表達式內的字串文字引號。

已棄用的表達式

$<CONFIGURATION>

組態名稱。自 CMake 3.0 起已棄用。請改用 CONFIG