cmake-generator-expressions(7)

簡介

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

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

這會根據所使用的 C++ 編譯器展開為 /opt/include/GNU/opt/include/Clang 等。

產生器表達式允許在許多目標屬性的上下文中使用,例如 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>

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

$<BOOL:string>

string 轉換為 01。如果以下任何一種情況為真,則評估為 0

  • string 為空,

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

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

否則會評估為 1

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

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

邏輯運算子

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

$<AND:conditions>

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

$<OR:conditions>

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

$<NOT:condition>

condition 的值必須為 01。如果 condition 的值為 1,則表達式的結果為 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>

如果 v1 的版本與 v2 相同,則為 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 版本新增。

list 的末尾附加每個 item。多個項目應以逗號分隔。

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

3.27 版本新增。

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

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

3.27 版本新增。

在指定的 index 處插入 item(或多個項目)的 list。多個項目應以逗號分隔。

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

$<LIST:POP_BACK,list>

3.27 版本新增。

刪除最後一個項目的 list

$<LIST:POP_FRONT,list>

3.27 版本新增。

刪除第一個項目的 list

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

3.27 版本新增。

刪除所有給定 value(或值)實例的 list。如果給出多個值,它們應該以逗號分隔。

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

3.27 版本新增。

刪除每個給定 index 處的項目的 list

$<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>

listglue 字串的內容連接起來,並在每個項目之間插入。這在概念上與 $<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

按檔案路徑的基本名稱排序檔案路徑列表。

NATURAL

使用自然順序排序字串列表(請參閱 strverscmp(3) 的手冊頁),以便將連續的數字作為整數進行比較。例如,如果選擇 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,根目錄也被認為有一個父目錄,它將是其本身。除非路徑僅包含 檔案名稱,否則結果為 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

路徑分解

這些表達式提供與 分解 選項等效的產生時功能,該選項屬於 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...>

如果請求的元件不存在於路徑中,則傳回空字串。

路徑轉換

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

在 3.27 版本中變更:所有操作現在都接受路徑清單作為引數。當指定路徑清單時,該操作將會套用至每個路徑。

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

在 3.24 版本中新增。

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

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

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

在 3.24 版本中新增。

使用 / 作為 directory-separator,傳回附加到 path 的所有 input 引數。根據 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 版本中新增。

傳回已移除副檔名(如果有的話)的 path

如需更多詳細資訊,請參閱 cmake_path(REMOVE_EXTENSION)

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

在 3.24 版本中新增。

傳回已將副檔名取代為 input(如果有的話)的 path

如需更多詳細資訊,請參閱 cmake_path(REPLACE_EXTENSION)

$<PATH:NORMAL_PATH,path...>

在 3.24 版本中新增。

傳回根據正規化中描述的步驟正規化的 path

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

在 3.24 版本中新增。

傳回已修改為相對於 base_directory 引數的 path

如需更多詳細資訊,請參閱 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 的引數用雙引號括在 CMake 原始碼中,這樣 ; 才不會分割引數。

組態表達式

$<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>

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

$<C_COMPILER_ID:compiler_ids>

其中 compiler_ids 是逗號分隔的列表。如果 C 編譯器的 CMake 編譯器 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 是一個以逗號分隔的清單。如果 C++ 編譯器的 CMake 編譯器 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 是一個以逗號分隔的清單。如果 CUDA 編譯器的 CMake 編譯器 ID 與 compiler_ids 中的任何一個項目相符,則為 1,否則為 0

$<OBJC_COMPILER_ID>

於 3.16 版本新增。

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

$<OBJC_COMPILER_ID:compiler_ids>

於 3.16 版本新增。

其中 compiler_ids 是一個以逗號分隔的清單。如果 Objective-C 編譯器的 CMake 編譯器 ID 與 compiler_ids 中的任何一個項目相符,則為 1,否則為 0

$<OBJCXX_COMPILER_ID>

於 3.16 版本新增。

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

$<OBJCXX_COMPILER_ID:compiler_ids>

於 3.16 版本新增。

其中 compiler_ids 是一個以逗號分隔的清單。如果 Objective-C++ 編譯器的 CMake 編譯器 ID 與 compiler_ids 中的任何一個項目相符,則為 1,否則為 0

$<Fortran_COMPILER_ID>

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

$<Fortran_COMPILER_ID:compiler_ids>

其中 compiler_ids 是一個以逗號分隔的清單。如果 Fortran 編譯器的 CMake 編譯器 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 是一個以逗號分隔的清單。如果 HIP 編譯器的 CMake 編譯器 ID 與 compiler_ids 中的任何一個項目相符,則為 1,否則為 0

$<ISPC_COMPILER_ID>

於 3.19 版本新增。

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

$<ISPC_COMPILER_ID:compiler_ids>

於 3.19 版本新增。

其中 compiler_ids 是一個以逗號分隔的清單。如果 ISPC 編譯器的 CMake 編譯器 ID 與 compiler_ids 中的任何一個項目相符,則為 1,否則為 0

$<C_COMPILER_FRONTEND_VARIANT>

在版本 3.30 中新增。

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

$<C_COMPILER_FRONTEND_VARIANT:compiler_ids>

在版本 3.30 中新增。

其中 compiler_ids 是一個以逗號分隔的清單。如果 C 編譯器的 CMake 編譯器前端變體與 compiler_ids 中的任何一個項目相符,則為 1,否則為 0

$<CXX_COMPILER_FRONTEND_VARIANT>

在版本 3.30 中新增。

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

$<CXX_COMPILER_FRONTEND_VARIANT:compiler_ids>

在版本 3.30 中新增。

其中 compiler_ids 是一個以逗號分隔的清單。如果 C++ 編譯器的 CMake 編譯器前端變體與 compiler_ids 中的任何一個項目相符,則為 1,否則為 0

$<CUDA_COMPILER_FRONTEND_VARIANT>

在版本 3.30 中新增。

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

$<CUDA_COMPILER_FRONTEND_VARIANT:compiler_ids>

在版本 3.30 中新增。

其中 compiler_ids 是一個以逗號分隔的清單。如果 CUDA 編譯器的 CMake 編譯器前端變體與 compiler_ids 中的任何一個項目相符,則為 1,否則為 0

$<OBJC_COMPILER_FRONTEND_VARIANT>

在版本 3.30 中新增。

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

$<OBJC_COMPILER_FRONTEND_VARIANT:compiler_ids>

在版本 3.30 中新增。

其中 compiler_ids 是一個以逗號分隔的清單。如果 Objective-C 編譯器的 CMake 編譯器前端變體與 compiler_ids 中的任何一個項目相符,則為 1,否則為 0

$<OBJCXX_COMPILER_FRONTEND_VARIANT>

在版本 3.30 中新增。

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

$<OBJCXX_COMPILER_FRONTEND_VARIANT:compiler_ids>

在版本 3.30 中新增。

其中 compiler_ids 是一個以逗號分隔的清單。如果 Objective-C++ 編譯器的 CMake 編譯器前端變體與 compiler_ids 中的任何一個項目相符,則為 1,否則為 0

$<Fortran_COMPILER_FRONTEND_VARIANT>

在版本 3.30 中新增。

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

$<Fortran_COMPILER_FRONTEND_VARIANT:compiler_ids>

在版本 3.30 中新增。

其中 compiler_ids 是一個以逗號分隔的清單。如果 Fortran 編譯器的 CMake 編譯器前端變體與 compiler_ids 中的任何一個項目相符,則為 1,否則為 0

$<HIP_COMPILER_FRONTEND_VARIANT>

在版本 3.30 中新增。

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

$<HIP_COMPILER_FRONTEND_VARIANT:compiler_ids>

在版本 3.30 中新增。

其中 compiler_ids 是一個以逗號分隔的清單。如果 HIP 編譯器的 CMake 編譯器前端變體與 compiler_ids 中的任何一個項目相符,則為 1,否則為 0

$<ISPC_COMPILER_FRONTEND_VARIANT>

在版本 3.30 中新增。

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

$<ISPC_COMPILER_FRONTEND_VARIANT:compiler_ids>

在版本 3.30 中新增。

其中 compiler_ids 是一個以逗號分隔的清單。如果 ISPC 編譯器的 CMake 編譯器前端變體與 compiler_ids 中的任何一個項目相符,則為 1,否則為 0

$<COMPILE_LANGUAGE>

在版本 3.3 中新增。

評估編譯選項時,原始程式碼檔案的編譯語言。關於此產生器表示式的可攜性,請參閱相關的布林表示式 $<COMPILE_LANGUAGE:language>

$<COMPILE_LANGUAGE:languages>

在版本 3.3 中新增。

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

當用於編譯單元的語言與 languages 中以逗號分隔的任何項目相符時,為 1,否則為 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++ 原始程式碼,則使用 CXX 評估 C 和 C++ 原始程式碼的表示式,否則使用 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 版本中新增。

當編譯單元使用的語言與 language 相符,且 CMake 中 language 編譯器的編譯器 ID 與 compiler_ids 中任何一個逗號分隔的項目相符時,評估結果為 1,否則為 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 和編譯語言指定不同的編譯定義。當 CXX 編譯器為 Clang 時,此範例將具有 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 是一個以逗號分隔的列表。如果所有 features 都適用於「head」目標,則評估結果為 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 版中新增。

當連結步驟使用的語言與 language 相符,且 CMake 中語言連結器的編譯器 ID 與 compiler_ids 中任何一個逗號分隔的項目相符時,評估結果為 1,否則為 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>

如果 policy 在建立 'head' 目標時為 NEW,則為 1,否則為 0。如果未設定 policy,將會發出該政策的警告訊息。此產生器表達式僅適用於一部分政策。

目標屬性

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

$<TARGET_PROPERTY:tgt,prop>

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

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

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

在版本 3.31 中變更: 遞移介面屬性的產生器表達式,例如 $<TARGET_PROPERTY:target,INTERFACE_*>,現在可以正確處理巢狀產生器表達式內的重複評估。先前,由於對遞移閉包的優化,這些重複評估傳回空值。此變更確保非聯集操作的一致評估。

$<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 相關聯的構件的資訊。除非另有說明,否則這可以是任何運行時構件,即

  • add_executable() 建立的可執行目標。

  • add_library() 建立的共享函式庫目標(.so.dll,但不包含它們的 .lib 匯入函式庫)。

  • add_library() 建立的靜態函式庫目標。

在以下內容中,「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 上的共享函式庫,它可能會分別是 .imp.tbd 匯入檔,具體取決於 ENABLE_EXPORTS 屬性的值。

當目標沒有相關的匯入檔時,此表達式會展開為空字串。

$<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 中新增。

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

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

$<TARGET_BUNDLE_DIR_NAME:tgt>

在 3.24 版本中新增。

bundle 目錄的名稱 ( my.app, my.framework, 或 my.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 命令,將目標依賴的所有 DLL 複製到其輸出目錄中的 POST_BUILD 自訂命令中。例如

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 模組 會產生類型為 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) 的程式碼引數或 install(SCRIPT) 的檔案引數中的安裝前置詞內容。

多層表達式評估

$<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