file

檔案操作命令。

此命令專用於需要存取檔案系統的檔案和路徑操作。

對於其他僅處理語法方面的路徑操作，請參閱cmake_path() 命令。

注意

子命令 RELATIVE_PATH、TO_CMAKE_PATH 和 TO_NATIVE_PATH 已被 cmake_path() 命令的子命令 RELATIVE_PATH、CONVERT ... TO_CMAKE_PATH_LIST 和 CONVERT ... TO_NATIVE_PATH_LIST 取代。

概要

Reading
  file(READ <filename> <out-var> [...])
  file(STRINGS <filename> <out-var> [...])
  file(<HASH> <filename> <out-var>)
  file(TIMESTAMP <filename> <out-var> [...])

Writing
  file({WRITE | APPEND} <filename> <content>...)
  file({TOUCH | TOUCH_NOCREATE} <file>...)
  file(GENERATE OUTPUT <output-file> [...])
  file(CONFIGURE OUTPUT <output-file> CONTENT <content> [...])

Filesystem
  file({GLOB | GLOB_RECURSE} <out-var> [...] <globbing-expr>...)
  file(MAKE_DIRECTORY <directories>...)
  file({REMOVE | REMOVE_RECURSE } <files>...)
  file(RENAME <oldname> <newname> [...])
  file(COPY_FILE <oldname> <newname> [...])
  file({COPY | INSTALL} <file>... DESTINATION <dir> [...])
  file(SIZE <filename> <out-var>)
  file(READ_SYMLINK <linkname> <out-var>)
  file(CREATE_LINK <original> <linkname> [...])
  file(CHMOD <files>... <directories>... PERMISSIONS <permissions>... [...])
  file(CHMOD_RECURSE <files>... <directories>... PERMISSIONS <permissions>... [...])

Path Conversion
  file(REAL_PATH <path> <out-var> [BASE_DIRECTORY <dir>] [EXPAND_TILDE])
  file(RELATIVE_PATH <out-var> <directory> <file>)
  file({TO_CMAKE_PATH | TO_NATIVE_PATH} <path> <out-var>)

Transfer
  file(DOWNLOAD <url> [<file>] [...])
  file(UPLOAD <file> <url> [...])

Locking
  file(LOCK <path> [...])

Archiving
  file(ARCHIVE_CREATE OUTPUT <archive> PATHS <paths>... [...])
  file(ARCHIVE_EXTRACT INPUT <archive> [...])

Handling Runtime Binaries
  file(GET_RUNTIME_DEPENDENCIES [...])

讀取

file(READ <filename> <variable> [OFFSET <offset>] [LIMIT <max-in>] [HEX])

從名為 <filename> 的檔案讀取內容，並將其儲存在 <variable> 中。可選擇從給定的 <offset> 開始，並讀取最多 <max-in> 個位元組。HEX 選項會將資料轉換為十六進位表示法（對於二進位資料很有用）。如果指定了 HEX 選項，則輸出中的字母（a 到 f）將以小寫形式顯示。

file(STRINGS <filename> <variable> <options>...)

從 <filename> 解析 ASCII 字串清單，並將其儲存在 <variable> 中。將忽略檔案中的二進位資料。忽略歸位符號（\r, CR）字元。選項有：

LENGTH_MAXIMUM <max-len>

僅考慮長度最多為給定長度的字串。

LENGTH_MINIMUM <min-len>

僅考慮長度至少為給定長度的字串。

LIMIT_COUNT <max-num>

限制要擷取的不同字串數量。

LIMIT_INPUT <max-in>

限制從檔案讀取的輸入位元組數。

LIMIT_OUTPUT <max-out>

限制儲存在 <variable> 中的總位元組數。

NEWLINE_CONSUME

將換行符號（\n, LF）視為字串內容的一部分，而不是在其處終止。

NO_HEX_CONVERSION

除非提供此選項，否則 Intel Hex 和 Motorola S-record 檔案在讀取時會自動轉換為二進位格式。

REGEX <regex>

僅考慮與給定的正規表示式相符的字串，如 string(REGEX) 下所述。

在 3.29 版本中變更：來自檔案中最後一個比對的捕獲群組會儲存在 CMAKE_MATCH_<n> 中，類似於 string(REGEX MATCHALL)。請參閱政策 CMP0159。

ENCODING <encoding-type>

在 3.1 版本中新增。

考慮給定編碼的字串。目前支援的編碼為：UTF-8、UTF-16LE、UTF-16BE、UTF-32LE、UTF-32BE。如果未提供 ENCODING 選項且檔案具有位元組順序標記，則 ENCODING 選項預設為符合位元組順序標記。

在 3.2 版本中新增：新增了 UTF-16LE、UTF-16BE、UTF-32LE、UTF-32BE 編碼。

例如，程式碼

file(STRINGS myfile.txt myfile)

會將一個清單儲存在變數 myfile 中，其中每個項目都是輸入檔案中的一行。

file(<HASH> <filename> <variable>)

計算 <filename> 內容的加密雜湊，並將其儲存在 <variable> 中。支援的 <HASH> 演算法名稱是 string(<HASH>) 命令列出的名稱。

file(TIMESTAMP <filename> <variable> [<format>] [UTC])

計算 <filename> 修改時間的字串表示，並將其儲存在 <variable> 中。如果命令無法取得時間戳記，變數將設定為空字串 ("")。

請參閱 string(TIMESTAMP) 命令，以取得 <format> 和 UTC 選項的文件。

寫入

file(WRITE <filename> <content>...)

file(APPEND <filename> <content>...)

將 <content> 寫入名為 <filename> 的檔案。如果檔案不存在，則將建立該檔案。如果檔案已存在，WRITE 模式會覆寫該檔案，而 APPEND 模式會附加到結尾。將建立由 <filename> 指定的路徑中任何不存在的目錄。

如果該檔案是組建輸入，請使用 configure_file() 命令，僅在檔案內容變更時更新檔案。

file(TOUCH <files>...)

file(TOUCH_NOCREATE <files>...)

在 3.12 版本中新增。

如果檔案尚不存在，則建立不含內容的檔案。如果檔案已存在，則其存取和/或修改將更新為執行函式呼叫時的時間。

如果檔案存在，請使用 TOUCH_NOCREATE 來觸碰該檔案，但不要建立它。如果檔案不存在，將會靜默忽略。

使用 TOUCH 和 TOUCH_NOCREATE 時，現有檔案的內容不會被修改。

在 3.30 版本中變更：<files> 可以是空列表。CMake 3.29 及更早版本要求至少要給定一個檔案。

file(GENERATE [...])

為目前 CMake 產生器 所支援的每個建置組態產生一個輸出檔案。從輸入內容評估 產生器 表達式，以產生輸出內容。

file(GENERATE OUTPUT <output-file>
     <INPUT <input-file>|CONTENT <content>>
     [CONDITION <expression>] [TARGET <target>]
     [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS |
      FILE_PERMISSIONS <permissions>...]
     [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])

選項如下

CONDITION <condition>

僅在條件為 true 時，才為特定組態產生輸出檔案。評估產生器表達式後，條件必須為 0 或 1。

CONTENT <content>

使用明確給定的內容作為輸入。

INPUT <input-file>

使用給定檔案的內容作為輸入。

在 3.10 版本中變更：相對路徑的處理會以 CMAKE_CURRENT_SOURCE_DIR 的值為基準。請參閱政策 CMP0070。

OUTPUT <output-file>

指定要產生的輸出檔案名稱。使用像是 $<CONFIG> 之類的產生器表達式，以指定組態特定的輸出檔案名稱。只有在產生的內容相同時，多個組態才能產生相同的輸出檔案。否則，<output-file> 必須評估為每個組態的唯一名稱。

在 3.10 版本中變更：相對路徑（在評估產生器表達式之後）的處理會以 CMAKE_CURRENT_BINARY_DIR 的值為基準。請參閱政策 CMP0070。

TARGET <target>

在 3.19 版本中新增。

指定在評估需要目標進行評估的產生器表達式時，要使用哪個目標（例如 $<COMPILE_FEATURES:...>、$<TARGET_PROPERTY:prop>）。

NO_SOURCE_PERMISSIONS

在 3.20 版本中新增。

產生的檔案權限預設為標準的 644 值 (-rw-r--r--)。

USE_SOURCE_PERMISSIONS

在 3.20 版本中新增。

將 INPUT 檔案的檔案權限轉移到產生的檔案。如果未給定三個與權限相關的關鍵字（NO_SOURCE_PERMISSIONS、USE_SOURCE_PERMISSIONS 或 FILE_PERMISSIONS），則這已是預設行為。USE_SOURCE_PERMISSIONS 關鍵字主要的作用是在呼叫端讓預期的行為更加明確。在沒有 INPUT 的情況下指定此選項是錯誤的。

FILE_PERMISSIONS <permissions>...

在 3.20 版本中新增。

對產生的檔案使用指定的權限。

NEWLINE_STYLE <style>

在 3.20 版本中新增。

指定產生檔案的換行符號樣式。指定 UNIX 或 LF 為 \n 換行符號，或指定 DOS、WIN32 或 CRLF 為 \r\n 換行符號。

必須給定正好一個 CONTENT 或 INPUT 選項。一個特定的 OUTPUT 檔案最多只能被一個 file(GENERATE) 呼叫所命名。只有在內容變更時，才會修改產生的檔案並更新其時間戳記，以供後續的 cmake 執行。

另請注意，file(GENERATE) 在產生階段才會建立輸出檔案。當 file(GENERATE) 命令返回時，輸出檔案尚未被寫入，它僅在處理完專案的所有 CMakeLists.txt 檔案後才會寫入。

file(CONFIGURE OUTPUT <output-file> CONTENT <content> [ESCAPE_QUOTES] [@ONLY] [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])

在 3.18 版本中新增。

使用 CONTENT 給定的輸入產生輸出檔案，並替換其中以 @VAR@ 或 ${VAR} 形式引用的變數值。替換規則的行為與 configure_file() 命令相同。為了符合 configure_file() 的行為，OUTPUT 和 CONTENT 都不支援產生器表達式，並且只有在內容變更或檔案先前不存在時，才會修改輸出檔案並更新其時間戳記。

引數如下

OUTPUT <output-file>

指定要產生的輸出檔案名稱。相對路徑的處理會以 CMAKE_CURRENT_BINARY_DIR 的值為基準。<output-file> 不支援產生器表達式。

CONTENT <content>

使用明確給定的內容作為輸入。<content> 不支援產生器表達式。

ESCAPE_QUOTES

使用反斜線 (C 樣式) 跳脫任何被取代的引號。

@ONLY

將變數替換限制為 @VAR@ 形式的引用。這對於設定使用 ${VAR} 語法的腳本很有用。

NEWLINE_STYLE <style>

指定輸出檔案的換行符號樣式。指定 UNIX 或 LF 為 \n 換行符號，或指定 DOS、WIN32 或 CRLF 為 \r\n 換行符號。

檔案系統

file(GLOB <variable> [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS] <globbing-expressions>...)

file(GLOB_RECURSE <variable> [FOLLOW_SYMLINKS] [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS] <globbing-expressions>...)

產生符合 <globbing-expressions> 的檔案列表，並將其儲存到 <variable> 中。Globbing 運算式類似於正規表示式，但更簡單。如果指定了 RELATIVE 旗標，結果將會以相對於給定路徑的相對路徑傳回。

在 3.6 版本變更: 結果將會依字典順序排序。

在 Windows 和 macOS 上，即使底層檔案系統區分大小寫，globbing 也不區分大小寫（檔案名稱和 globbing 運算式在比對前都會轉換為小寫）。在其他平台上，globbing 會區分大小寫。

在 3.3 版本新增: 預設情況下，GLOB 會列出目錄。如果 LIST_DIRECTORIES 設定為 false，則結果中會省略目錄。

在 3.12 版本新增: 如果指定了 CONFIGURE_DEPENDS 旗標，CMake 會在主要建置系統檢查目標中新增邏輯，以便在建置時重新執行標記的 GLOB 命令。如果任何輸出發生變更，CMake 將會重新產生建置系統。

注意

我們不建議使用 GLOB 從您的原始程式碼樹狀結構中收集原始程式碼檔案的列表。如果新增或移除原始程式碼時沒有任何 CMakeLists.txt 檔案變更，則產生的建置系統將無法知道何時要求 CMake 重新產生。 CONFIGURE_DEPENDS 旗標可能無法在所有產生器上可靠地運作，或者如果未來新增了無法支援它的新產生器，則使用它的專案將會被卡住。即使 CONFIGURE_DEPENDS 可靠地運作，每次重建時執行檢查仍然會產生成本。

Globbing 運算式的範例包括：

*.cxx	比對所有副檔名為 cxx 的檔案
*.vt?	比對所有副檔名為 vta、...、vtz 的檔案
f[3-5].txt	比對檔案 f3.txt、f4.txt、f5.txt

GLOB_RECURSE 模式將會遍歷比對目錄的所有子目錄，並比對檔案。如果給定了 FOLLOW_SYMLINKS 或者原則 CMP0009 未設定為 NEW，則僅會遍歷為符號連結的子目錄。

在 3.3 版本新增: 預設情況下，GLOB_RECURSE 會從結果列表中省略目錄。將 LIST_DIRECTORIES 設定為 true 會將目錄新增到結果列表中。如果給定了 FOLLOW_SYMLINKS 或者原則 CMP0009 未設定為 NEW，則 LIST_DIRECTORIES 會將符號連結視為目錄。

遞迴 globbing 的範例包括：

/dir/*.py

比對 /dir 和子目錄中的所有 python 檔案

file(MAKE_DIRECTORY <directories>... [RESULT <result>])

視需要建立給定的目錄及其父目錄。

選項如下

RESULT <result>

在 3.31 版本新增。

成功時，將 <result> 變數設定為 0，否則設定為錯誤訊息。如果未指定 RESULT 且作業失敗，則會發出錯誤訊息。

在 3.30 版本變更: <directories> 可以是空列表。CMake 3.29 和更早版本要求必須至少給定一個目錄。

file(REMOVE <files>...)

file(REMOVE_RECURSE <files>...)

移除給定的檔案。REMOVE_RECURSE 模式將會移除給定的檔案和目錄，包括非空的目錄。如果給定的檔案不存在，則不會發出錯誤訊息。相對於目前來源目錄評估相對輸入路徑。

在 3.15 版本變更: 會忽略空輸入路徑並發出警告。先前的 CMake 版本將空字串解讀為相對於目前目錄的相對路徑，並移除其內容。

file(RENAME <oldname> <newname> [RESULT <result>] [NO_REPLACE])

在檔案系統中，將檔案或目錄從 <oldname> 移動到 <newname>，並以原子方式取代目的地。

選項如下

RESULT <result>

在 3.21 版本新增。

成功時，將 <result> 變數設定為 0，否則設定為錯誤訊息。如果未指定 RESULT 且作業失敗，則會發出錯誤訊息。

NO_REPLACE

在 3.21 版本新增。

如果 <newname> 路徑已存在，則不要取代它。如果使用了 RESULT <result>，則結果變數將會設定為 NO_REPLACE。否則，將會發出錯誤訊息。

file(COPY_FILE <oldname> <newname> [RESULT <result>] [ONLY_IF_DIFFERENT] [INPUT_MAY_BE_RECENT])

在 3.21 版本新增。

將檔案從 <oldname> 複製到 <newname>。不支援目錄。會忽略符號連結，並將 <oldfile> 的內容讀取並寫入到 <newname> 作為新檔案。

選項如下

RESULT <result>

成功時，將 <result> 變數設定為 0，否則設定為錯誤訊息。如果未指定 RESULT 且作業失敗，則會發出錯誤訊息。

ONLY_IF_DIFFERENT

如果 <newname> 路徑已存在，且檔案內容與 <oldname> 相同，則不要取代它（這會避免更新 <newname> 的時間戳記）。

INPUT_MAY_BE_RECENT

在 3.26 版本新增。

告知 CMake 輸入檔案可能是最近建立的。這僅在 Windows 上有意義，因為檔案在建立後可能會在短時間內無法存取。使用此選項，如果拒絕許可，CMake 將會重試讀取輸入幾次。

此子命令與具有 COPYONLY 選項的 configure_file() 有些相似之處。一個重要的差異是 configure_file() 會建立對來源檔案的依賴性，因此如果來源檔案變更，則會重新執行 CMake。 file(COPY_FILE) 子命令不會建立這種依賴性。

另請參閱下方提供的 file(COPY) 子命令，它提供了進一步的檔案複製功能。

file(COPY [...])

file(INSTALL [...])

COPY 簽名會將檔案、目錄和符號連結複製到目標資料夾。相對輸入路徑會根據目前的來源目錄進行評估，而相對目標路徑則根據目前的建置目錄進行評估。複製作業會保留輸入檔案的時間戳記，如果目標位置已存在具有相同時間戳記的檔案，則會最佳化略過該檔案。除非指定明確的權限或 NO_SOURCE_PERMISSIONS，否則複製會保留輸入權限（預設為 USE_SOURCE_PERMISSIONS）。

file(<COPY|INSTALL> <files>... DESTINATION <dir>
     [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS]
     [FILE_PERMISSIONS <permissions>...]
     [DIRECTORY_PERMISSIONS <permissions>...]
     [FOLLOW_SYMLINK_CHAIN]
     [FILES_MATCHING]
     [[PATTERN <pattern> | REGEX <regex>]
      [EXCLUDE] [PERMISSIONS <permissions>...]] [...])

注意

對於簡單的檔案複製操作，使用上方的 file(COPY_FILE) 子命令可能會更容易。

在版本 3.15 中新增：如果指定 FOLLOW_SYMLINK_CHAIN，COPY 將會遞迴解析指定路徑的符號連結，直到找到真實的檔案，並在目標位置為每個遇到的符號連結安裝對應的符號連結。對於每個安裝的符號連結，解析會去除目錄，僅留下檔案名稱，這表示新的符號連結會指向與該符號連結位於相同目錄中的檔案。此功能在某些 Unix 系統上很有用，這些系統的程式庫會以帶有版本號碼的符號連結鏈的形式安裝，其中不太特定的版本會指向更特定的版本。FOLLOW_SYMLINK_CHAIN 會將所有這些符號連結和程式庫本身安裝到目標目錄中。例如，如果您有以下目錄結構

• /opt/foo/lib/libfoo.so.1.2.3

• /opt/foo/lib/libfoo.so.1.2 -> libfoo.so.1.2.3

• /opt/foo/lib/libfoo.so.1 -> libfoo.so.1.2

• /opt/foo/lib/libfoo.so -> libfoo.so.1

而您執行

file(COPY /opt/foo/lib/libfoo.so DESTINATION lib FOLLOW_SYMLINK_CHAIN)

這會將所有符號連結和 libfoo.so.1.2.3 本身安裝到 lib 中。

請參閱 install(DIRECTORY) 命令，以取得關於權限、FILES_MATCHING、PATTERN、REGEX 和 EXCLUDE 選項的文件。複製目錄會保留其內容的結構，即使使用選項來選取檔案的子集也是如此。

INSTALL 簽名與 COPY 略有不同：它會列印狀態訊息，並且預設為 NO_SOURCE_PERMISSIONS。由 install() 命令產生的安裝腳本會使用此簽名（並帶有一些未記載的內部使用選項）。

在版本 3.22 中變更：環境變數 CMAKE_INSTALL_MODE 可以覆寫 file(INSTALL) 的預設複製行為。

file(SIZE <filename> <variable>)

在版本 3.14 中新增。

判斷 <filename> 的檔案大小，並將結果放入 <variable> 變數中。這需要 <filename> 是指向檔案且可讀取的有效路徑。

file(READ_SYMLINK <linkname> <variable>)

在版本 3.14 中新增。

查詢符號連結 <linkname>，並將它指向的路徑儲存在結果 <variable> 中。如果 <linkname> 不存在或不是符號連結，CMake 會發出嚴重錯誤。

請注意，此命令會傳回原始符號連結路徑，且不會解析相對路徑。以下範例示範如何確保取得絕對路徑

set(linkname "/path/to/foo.sym")
file(READ_SYMLINK "${linkname}" result)
if(NOT IS_ABSOLUTE "${result}")
  get_filename_component(dir "${linkname}" DIRECTORY)
  set(result "${dir}/${result}")
endif()

file(CREATE_LINK <original> <linkname> [RESULT <result>] [COPY_ON_ERROR] [SYMBOLIC])

在版本 3.14 中新增。

建立一個指向 <original> 的連結 <linkname>。它預設會是硬連結，但提供 SYMBOLIC 選項會改為產生符號連結。硬連結需要 original 存在且為檔案，而非目錄。如果 <linkname> 已存在，則會被覆寫。

如果指定了 <result> 變數，它會接收操作的狀態。成功時會設定為 0，否則會設定為錯誤訊息。如果未指定 RESULT 且操作失敗，則會發出嚴重錯誤。

如果建立連結失敗，指定 COPY_ON_ERROR 會啟用複製檔案作為回退。它對於處理諸如 <original> 和 <linkname> 位於不同磁碟機或掛載點的情況很有用，這會導致它們無法支援硬連結。

file(CHMOD <files>... <directories>... [PERMISSIONS <permissions>...] [FILE_PERMISSIONS <permissions>...] [DIRECTORY_PERMISSIONS <permissions>...])

在 3.19 版本中新增。

設定指定的 <files>... 和 <directories>... 的權限。有效的權限包括 OWNER_READ、OWNER_WRITE、OWNER_EXECUTE、GROUP_READ、GROUP_WRITE、GROUP_EXECUTE、WORLD_READ、WORLD_WRITE、WORLD_EXECUTE、SETUID、SETGID。

關鍵字的有效組合為

PERMISSIONS

所有項目都會變更。

FILE_PERMISSIONS

只有檔案會變更。

DIRECTORY_PERMISSIONS

只有目錄會變更。

PERMISSIONS 和 FILE_PERMISSIONS

FILE_PERMISSIONS 會覆寫檔案的 PERMISSIONS。

PERMISSIONS 和 DIRECTORY_PERMISSIONS

DIRECTORY_PERMISSIONS 會覆寫目錄的 PERMISSIONS。

FILE_PERMISSIONS 和 DIRECTORY_PERMISSIONS

檔案請使用 FILE_PERMISSIONS，目錄請使用 DIRECTORY_PERMISSIONS。

file(CHMOD_RECURSE <files>... <directories>... [PERMISSIONS <permissions>...] [FILE_PERMISSIONS <permissions>...] [DIRECTORY_PERMISSIONS <permissions>...])

在 3.19 版本中新增。

與 CHMOD 相同，但會遞迴地變更 <directories>... 中出現的檔案和目錄的權限。

路徑轉換

file(REAL_PATH <path> <out-var> [BASE_DIRECTORY <dir>] [EXPAND_TILDE])

在 3.19 版本中新增。

計算已存在的檔案或目錄的絕對路徑，並解析符號連結。選項如下：

BASE_DIRECTORY <dir>

如果提供的 <path> 是相對路徑，則會以給定的基礎目錄 <dir> 為基準進行評估。如果未提供基礎目錄，則預設的基礎目錄將會是 CMAKE_CURRENT_SOURCE_DIR。

EXPAND_TILDE

在 3.21 版本新增。

如果 <path> 是 ~ 或以 ~/ 開頭，則 ~ 會被替換為使用者的主目錄。主目錄的路徑會從環境變數中取得。在 Windows 上，會使用 USERPROFILE 環境變數，如果未定義 USERPROFILE 則會回退使用 HOME 環境變數。在所有其他平台上，僅使用 HOME。

變更於 3.28 版本: 在摺疊 ../ 元件之前，會先解析所有符號連結。請參閱政策 CMP0152。

file(RELATIVE_PATH <variable> <directory> <file>)

計算從 <directory> 到 <file> 的相對路徑，並將其儲存在 <variable> 中。

file(TO_CMAKE_PATH "<path>" <variable>)

file(TO_NATIVE_PATH "<path>" <variable>)

TO_CMAKE_PATH 模式會將原生 <path> 轉換為使用正斜線 (/) 的 cmake 風格路徑。輸入可以是單一路徑或像是 $ENV{PATH} 的系統搜尋路徑。搜尋路徑會被轉換為以 ; 字元分隔的 cmake 風格清單。

TO_NATIVE_PATH 模式會將 cmake 風格的 <path> 轉換為使用平台特定斜線的原生路徑（在 Windows 主機上是 \，其他地方是 /）。

請務必在 <path> 周圍使用雙引號，以確保它被視為此命令的單一引數。

傳輸

file(DOWNLOAD <url> [<file>] <options>...)

file(UPLOAD <file> <url> <options>...)

DOWNLOAD 子命令會將給定的 <url> 下載到本機 <file>。UPLOAD 模式會將本機 <file> 上傳到給定的 <url>。

新增於 3.19 版本: 如果未為 file(DOWNLOAD) 指定 <file>，則不會儲存該檔案。如果您想知道是否可以下載檔案（例如，檢查它是否存在），而無需將其儲存到任何地方，這可能會很有用。

DOWNLOAD 和 UPLOAD 的選項如下：

INACTIVITY_TIMEOUT <seconds>

在一段非活動時間後終止操作。

LOG <variable>

將操作的人工可讀日誌儲存在變數中。

SHOW_PROGRESS

列印進度資訊作為狀態訊息，直到操作完成。

STATUS <variable>

將操作的結果狀態儲存在變數中。狀態是一個長度為 2 的 ; 分隔清單。第一個元素是操作的數值回傳值，第二個元素是錯誤的字串值。數值錯誤 0 表示操作中沒有錯誤。

TIMEOUT <seconds>

在經過給定的總時間後終止操作。

USERPWD <username>:<password>

新增於 3.7 版本。

設定操作的使用者名稱和密碼。

HTTPHEADER <HTTP-header>

新增於 3.7 版本。

DOWNLOAD 和 UPLOAD 操作的 HTTP 標頭。HTTPHEADER 可以重複用於多個選項。

file(DOWNLOAD <url>
     HTTPHEADER "Authorization: Bearer <auth-token>"
     HTTPHEADER "UserAgent: Mozilla/5.0")

NETRC <level>

新增於 3.11 版本。

指定是否將 .netrc 檔案用於操作。如果未指定此選項，則會改用 CMAKE_NETRC 變數的值。

有效層級為：

IGNORED

會忽略 .netrc 檔案。這是預設值。

OPTIONAL

.netrc 檔案是可選的，並且 URL 中的資訊優先。將會掃描該檔案以查找 URL 中未指定的任何資訊。

REQUIRED

需要 .netrc 檔案，並且會忽略 URL 中的資訊。

NETRC_FILE <file>

新增於 3.11 版本。

如果 NETRC 層級為 OPTIONAL 或 REQUIRED，請指定您主目錄中的 .netrc 檔案的替代檔案。如果未指定此選項，則會改用 CMAKE_NETRC_FILE 變數的值。

TLS_VERSION <min>

新增於 3.30 版本。

指定 https:// URL 的最低 TLS 版本。如果未指定此選項，則會改用 CMAKE_TLS_VERSION 變數或 CMAKE_TLS_VERSION 環境變數的值。請參閱 CMAKE_TLS_VERSION 以取得允許的值。

變更於 3.31 版本: 預設值為 TLS 1.2。先前，預設情況下不強制執行最低版本。

TLS_VERIFY <ON|OFF>

指定是否要驗證 https:// URL 的伺服器憑證。如果未指定此選項，則會改用 CMAKE_TLS_VERIFY 變數或 CMAKE_TLS_VERIFY 環境變數的值。如果兩者都未設定，則預設為開啟。

在 3.31 版本中變更: 預設為開啟。先前，預設為關閉。使用者可以將 CMAKE_TLS_VERIFY 環境變數設定為 0 以還原舊的預設值。

在 3.18 版本中新增: 新增對 file(UPLOAD) 的支援。

TLS_CAINFO <file>

指定 https:// URL 的自訂憑證授權單位檔案。如果未指定此選項，則會改用 CMAKE_TLS_CAINFO 變數的值。

在 3.18 版本中新增: 新增對 file(UPLOAD) 的支援。

對於 https:// URL，CMake 必須使用 SSL/TLS 支援來建置。

DOWNLOAD 的其他選項為

EXPECTED_HASH <algorithm>=<value>

驗證下載內容的雜湊是否符合預期值，其中 <algorithm> 是 <HASH> 支援的演算法之一。如果檔案已存在且雜湊相符，則會跳過下載。如果檔案已存在且雜湊不符，則會再次下載該檔案。如果在下載後檔案的雜湊不符，則操作會失敗並產生錯誤。如果未對 DOWNLOAD 給定 <file>，則指定此選項會產生錯誤。

EXPECTED_MD5 <value>

EXPECTED_HASH MD5=<value> 的歷史簡寫。如果未對 DOWNLOAD 給定 <file>，則指定此選項會產生錯誤。

RANGE_START <value>

在 3.24 版本中新增。

檔案中範圍起始位置的位元組偏移量。可以省略以僅下載到指定的 RANGE_END。

RANGE_END <value>

在 3.24 版本中新增。

檔案中範圍結束位置的位元組偏移量。可以省略以僅下載從指定的 RANGE_START 到檔案結尾的所有內容。

鎖定

file(LOCK <path> [DIRECTORY] [RELEASE] [GUARD <FUNCTION|FILE|PROCESS>] [RESULT_VARIABLE <variable>] [TIMEOUT <seconds>])

在 3.2 版本中新增。

如果沒有 DIRECTORY 選項，則鎖定由 <path> 指定的檔案；否則鎖定檔案 <path>/cmake.lock。檔案將在 GUARD 選項定義的範圍內鎖定（預設值為 PROCESS）。可以使用 RELEASE 選項明確解除鎖定檔案。如果未指定 TIMEOUT 選項，CMake 將會等待直到鎖定成功或發生嚴重錯誤。如果 TIMEOUT 設定為 0，則會嘗試鎖定一次，並立即報告結果。如果 TIMEOUT 不為 0，CMake 將會嘗試在 TIMEOUT <seconds> 值指定的時間內鎖定檔案。如果沒有 RESULT_VARIABLE 選項，任何錯誤都會被視為嚴重錯誤。否則，結果會儲存在 <variable> 中，並且在成功時為 0，或在失敗時為錯誤訊息。

請注意，鎖定是建議性的；無法保證其他處理程序會遵守此鎖定，也就是說，鎖定會同步兩個或多個共用某些可修改資源的 CMake 執行個體。類似的邏輯也適用於 DIRECTORY 選項；鎖定父目錄不會阻止其他 LOCK 命令鎖定任何子目錄或檔案。

不允許嘗試鎖定同一個檔案兩次。如果不存在，則會建立任何中間目錄和檔案本身。GUARD 和 TIMEOUT 選項在 RELEASE 操作時會被忽略。

封存

file(ARCHIVE_CREATE OUTPUT <archive> PATHS <paths>... [FORMAT <format>] [COMPRESSION <compression> [COMPRESSION_LEVEL <compression-level>]] [MTIME <mtime>] [WORKING_DIRECTORY <dir>] [VERBOSE])

在 3.18 版本中新增。

使用 <paths> 中列出的檔案和目錄，建立指定的 <archive> 檔案。請注意，<paths> 必須列出實際的檔案或目錄；不支援萬用字元。

選項如下

FORMAT <format>

指定封存格式。 <format> 的支援值為 7zip、gnutar、pax、paxr、raw 和 zip。如果未給定 FORMAT，則預設格式為 paxr。

COMPRESSION <compression>

某些封存格式允許指定壓縮類型。7zip 和 zip 封存格式已經暗示了特定的壓縮類型。其他格式預設不使用壓縮，但可以使用 COMPRESSION 選項來指示進行壓縮。 <compression> 的有效值為 None、BZip2、GZip、XZ 和 Zstd。

注意

當 FORMAT 設定為 raw 時，只會使用 COMPRESSION 指定的壓縮類型壓縮一個檔案。

COMPRESSION_LEVEL <compression-level>

在 3.19 版本中新增。

可以使用 COMPRESSION_LEVEL 選項指定壓縮層級。<compression-level> 應介於 0-9 之間，預設值為 0。當給定 COMPRESSION_LEVEL 時，COMPRESSION 選項必須存在。

在 3.26 版本中新增: Zstd 演算法的 <compression-level> 可以設定在 0-19 之間。

MTIME <mtime>

指定在 tarball 項目中記錄的修改時間。

WORKING_DIRECTORY <dir>

在 3.31 版本新增。

指定將執行封存檔建立作業的目錄。 <paths> 引數中的路徑可以是相對於此目錄的相對路徑。如果未提供此選項，預設會使用目前的工作目錄。

VERBOSE

啟用封存作業的詳細輸出。

file(ARCHIVE_EXTRACT INPUT <archive> [DESTINATION <dir>] [PATTERNS <pattern>...] [LIST_ONLY] [VERBOSE] [TOUCH])

在 3.18 版本中新增。

解壓縮或列出指定的 <archive> 的內容。

選項如下

DESTINATION <dir>

指定將在其中解壓縮封存檔內容的目錄。如果目錄不存在，將會建立該目錄。如果未提供 DESTINATION，則會使用目前的二進位目錄。

PATTERNS <pattern>...

僅解壓縮/列出符合其中一個指定模式的檔案和目錄。支援萬用字元。如果未提供 PATTERNS 選項，將會列出或解壓縮整個封存檔。

LIST_ONLY

列出封存檔中的檔案，而不是解壓縮它們。

TOUCH

在 3.24 版本中新增。

給予解壓縮的檔案目前的本機時間戳記，而不是從封存檔解壓縮檔案時間戳記。

VERBOSE

啟用解壓縮作業的詳細輸出。

注意

此子指令的工作目錄是 DESTINATION 目錄（已提供或已計算），除非指定了 LIST_ONLY。因此，在腳本模式之外，最好為 INPUT 封存檔提供絕對路徑，因為它們不太可能在相對路徑有效的位置解壓縮。

處理執行階段二進位檔

file(GET_RUNTIME_DEPENDENCIES [...])

在 3.16 版中新增。

遞迴取得給定檔案所依賴的函式庫清單

file(GET_RUNTIME_DEPENDENCIES
  [RESOLVED_DEPENDENCIES_VAR <deps_var>]
  [UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>]
  [CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>]
  [EXECUTABLES <executable_files>...]
  [LIBRARIES <library_files>...]
  [MODULES <module_files>...]
  [DIRECTORIES <directories>...]
  [BUNDLE_EXECUTABLE <bundle_executable_file>]
  [PRE_INCLUDE_REGEXES <regexes>...]
  [PRE_EXCLUDE_REGEXES <regexes>...]
  [POST_INCLUDE_REGEXES <regexes>...]
  [POST_EXCLUDE_REGEXES <regexes>...]
  [POST_INCLUDE_FILES <files>...]
  [POST_EXCLUDE_FILES <files>...]
  )

請注意，此子指令不適用於專案模式。它適用於安裝時使用，可以是從 install(RUNTIME_DEPENDENCY_SET) 命令產生的程式碼，或從專案透過 install(CODE) 或 install(SCRIPT) 提供的程式碼。例如

install(CODE [[
  file(GET_RUNTIME_DEPENDENCIES
    # ...
    )
  ]])

引數如下

RESOLVED_DEPENDENCIES_VAR <deps_var>

儲存已解析相依性清單的變數名稱。

UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>

儲存未解析相依性清單的變數名稱。如果未指定此變數，而且有任何未解析的相依性，則會發出錯誤。

CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>

儲存衝突相依性資訊的變數前置詞。如果發現兩個名稱相同的檔案位於兩個不同的目錄中，則相依性會發生衝突。衝突的檔案名稱清單儲存在 <conflicting_deps_prefix>_FILENAMES 中。對於每個檔案名稱，找到的該檔案名稱的路徑清單會儲存在 <conflicting_deps_prefix>_<filename> 中。

EXECUTABLES <executable_files>...

要讀取相依性的可執行檔清單。這些是通常使用 add_executable() 建立的可執行檔，但它們不一定要由 CMake 建立。在 Apple 平台上，這些檔案的路徑會決定遞迴解析函式庫時 @executable_path 的值。在此處指定任何類型的函式庫（STATIC、MODULE 或 SHARED）將會導致未定義的行為。

LIBRARIES <library_files>...

要讀取相依性的函式庫檔案清單。這些是通常使用 add_library(SHARED) 建立的函式庫，但它們不一定要由 CMake 建立。在此處指定 STATIC 函式庫、MODULE 函式庫或可執行檔將會導致未定義的行為。

MODULES <module_files>...

要讀取相依性的可載入模組檔案清單。這些是通常使用 add_library(MODULE) 建立的模組，但它們不一定要由 CMake 建立。它們通常透過在執行階段呼叫 dlopen() 來使用，而不是在連結時透過 ld -l 連結。在此處指定 STATIC 函式庫、SHARED 函式庫或可執行檔將會導致未定義的行為。

DIRECTORIES <directories>...

要搜尋相依性的其他目錄清單。在 Linux 平台上，如果在任何其他常用路徑中找不到相依性，則會搜尋這些目錄。如果在此類目錄中找到，則會發出警告，因為這表示檔案不完整（它未列出包含其相依性的所有目錄）。在 Windows 平台上，如果在任何其他搜尋路徑中都找不到相依性，則會搜尋這些目錄，但不會發出警告，因為搜尋其他路徑是 Windows 相依性解析的正常部分。在 Apple 平台上，此引數無效。

BUNDLE_EXECUTABLE <bundle_executable_file>

在解析函式庫時，要視為「套件可執行檔」的可執行檔。在 Apple 平台上，此引數會決定遞迴解析 LIBRARIES 和 MODULES 檔案的函式庫時 @executable_path 的值。它對 EXECUTABLES 檔案沒有影響。在其他平台上，它沒有影響。這通常（但不總是）是 EXECUTABLES 引數中指定套件「主要」可執行檔的可執行檔之一。

以下引數指定用於包含或排除要解析的函式庫的篩選器。請參閱下文以取得其運作方式的完整說明。

PRE_INCLUDE_REGEXES <regexes>...

要篩選尚未解析的相依性名稱的預先包含正規表示式清單。

PRE_EXCLUDE_REGEXES <regexes>...

要篩選尚未解析的相依性名稱的預先排除正規表示式清單。

POST_INCLUDE_REGEXES <regexes>...

要篩選已解析相依性名稱的後續包含正規表示式清單。

POST_EXCLUDE_REGEXES <regexes>...

要篩選已解析相依性名稱的後續排除正規表示式清單。

POST_INCLUDE_FILES <files>...

在 3.21 版本新增。

要篩選已解析相依性名稱的後續包含檔案名稱清單。嘗試比對這些檔案名稱時，會解析符號連結。

POST_EXCLUDE_FILES <files>...

在 3.21 版本新增。

要篩選已解析相依性名稱的後續排除檔案名稱清單。嘗試比對這些檔案名稱時，會解析符號連結。

這些引數可用於在解析相依性時排除不需要的系統函式庫，或從特定目錄中包含函式庫。篩選的工作方式如下

1. 如果尚未解析的相依性符合任何 PRE_INCLUDE_REGEXES，則會跳過步驟 2 和 3，並且相依性解析會繼續進行到步驟 4。

2. 如果尚未解析的相依性符合任何 PRE_EXCLUDE_REGEXES，則會停止該相依性的相依性解析。

3. 否則，相依性解析會繼續進行。

4. file(GET_RUNTIME_DEPENDENCIES) 會根據平台的連結規則搜尋相依性（請參閱下文）。

5. 如果找到相依性，且其完整路徑符合其中一個 POST_INCLUDE_REGEXES 或 POST_INCLUDE_FILES，則會將完整路徑新增至已解析的相依性，並且 file(GET_RUNTIME_DEPENDENCIES) 會遞迴解析該函式庫本身的相依性。否則，解析會繼續進行到步驟 6。

6. 如果找到相依性，但其完整路徑符合其中一個 POST_EXCLUDE_REGEXES 或 POST_EXCLUDE_FILES，則不會將其新增至已解析的相依性，並且會停止該相依性的相依性解析。

7. 如果找到相依性，且其完整路徑不符合 POST_INCLUDE_REGEXES、 POST_INCLUDE_FILES、 POST_EXCLUDE_REGEXES 或 POST_EXCLUDE_FILES，則會將完整路徑新增至已解析的相依性中，並由 file(GET_RUNTIME_DEPENDENCIES) 遞迴解析該程式庫本身的相依性。

不同的平台對於如何解析相依性有不同的規則。這些細節在此處說明。

在 Linux 平台上，程式庫解析的運作方式如下：

1. 如果相依檔案沒有任何 RUNPATH 條目，且該程式庫存在於相依檔案的 RPATH 條目之一，或其父目錄中 (依此順序)，則相依性會解析為該檔案。

2. 否則，如果相依檔案有任何 RUNPATH 條目，且該程式庫存在於這些條目之一，則相依性會解析為該檔案。

3. 否則，如果該程式庫存在於 ldconfig 所列出的目錄之一，則相依性會解析為該檔案。

4. 否則，如果該程式庫存在於 DIRECTORIES 條目之一，則相依性會解析為該檔案。在此情況下，會發出警告，因為在 DIRECTORIES 之一中找到檔案表示相依檔案不完整 (它未列出它從中提取相依性的所有目錄)。

5. 否則，相依性無法解析。

在 3.31 版本中變更：在處理給定的根 ELF 檔案 (可執行檔或共享物件) 時，每個遇到的程式庫檔案名稱的解析最多只會發生一次。如果在相依性樹狀結構中再次遇到程式庫檔案名稱，則會假設原始解析。此行為更接近 Linux 上動態載入器的行為。

在 Windows 平台上，程式庫解析的運作方式如下：

1. DLL 相依性名稱會轉換為小寫，以便進行篩選。Windows DLL 名稱不區分大小寫，且某些連結器會損壞 DLL 相依性名稱的大小寫。然而，這使得 PRE_INCLUDE_REGEXES、 PRE_EXCLUDE_REGEXES、 POST_INCLUDE_REGEXES 和 POST_EXCLUDE_REGEXES 更難以正確篩選 DLL 名稱 - 每個 regex 都必須檢查大寫和小寫字母。例如：

   file(GET_RUNTIME_DEPENDENCIES
     # ...
     PRE_INCLUDE_REGEXES "^[Mm][Yy][Ll][Ii][Bb][Rr][Aa][Rr][Yy]\\.[Dd][Ll][Ll]$"
     )
   

   將 DLL 名稱轉換為小寫可讓 regex 只比對小寫名稱，從而簡化 regex。例如：

   file(GET_RUNTIME_DEPENDENCIES
     # ...
     PRE_INCLUDE_REGEXES "^mylibrary\\.dll$"
     )
   

   無論 mylibrary.dll 的大小寫如何 (無論是在磁碟上或在相依檔案中)，此 regex 都會比對 mylibrary.dll。(例如，它會比對 mylibrary.dll、 MyLibrary.dll 和 MYLIBRARY.DLL。)

   在 3.27 版本中變更：轉換為小寫僅適用於比對篩選器。篩選後回報的結果會保留每個 DLL 名稱在磁碟上找到時的大小寫 (如果已解析)，否則會保留其由相依二進制檔所參考的大小寫。

   在 CMake 3.27 之前，回報的結果會使用小寫 DLL 檔案名稱，但目錄部分會保留其大小寫。

2. (尚未實作) 如果相依檔案是 Windows Store 應用程式，且相依性在應用程式的套件資訊清單中列為相依性，則相依性會解析為該檔案。

3. 否則，如果程式庫存在於與相依檔案相同的目錄中，則相依性會解析為該檔案。

4. 否則，如果程式庫存在於作業系統的 system32 目錄或 Windows 目錄中 (依此順序)，則相依性會解析為該檔案。

5. 否則，如果程式庫存在於 DIRECTORIES 指定的目錄之一 (依列出順序)，則相依性會解析為該檔案。在此情況下，不會發出警告，因為搜尋其他目錄是 Windows 程式庫解析的正常部分。

6. 否則，相依性無法解析。

在 Apple 平台上，程式庫解析的運作方式如下：

1. 如果相依性以 @executable_path/ 開頭，且正在解析 EXECUTABLES 引數，並將 @executable_path/ 取代為可執行檔的目錄會產生現有檔案，則相依性會解析為該檔案。

2. 否則，如果相依性以 @executable_path/ 開頭，且有 BUNDLE_EXECUTABLE 引數，並將 @executable_path/ 取代為套件可執行檔的目錄會產生現有檔案，則相依性會解析為該檔案。

3. 否則，如果相依性以 @loader_path/ 開頭，並將 @loader_path/ 取代為相依檔案的目錄會產生現有檔案，則相依性會解析為該檔案。

4. 否則，如果相依性以 @rpath/ 開頭，並將 @rpath/ 取代為相依檔案的 RPATH 條目之一會產生現有檔案，則相依性會解析為該檔案。請注意，以 @executable_path/ 或 @loader_path/ 開頭的 RPATH 條目也會將這些項目取代為適當的路徑。

5. 否則，如果相依性是存在的絕對檔案，則相依性會解析為該檔案。

6. 否則，相依性無法解析。

此函式接受數個變數，這些變數會決定使用哪個工具進行相依性解析：

CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM

決定檔案是針對哪個作業系統和可執行檔格式所建置的。這可能是下列其中一個值：

• linux+elf

• windows+pe

• macos+macho

如果未指定此變數，則會透過系統內省自動判斷。

CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL

決定用於相依性解析的工具。它可能是下列其中一個值，取決於 CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM 的值。

CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM	CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL
linux+elf	objdump
windows+pe	objdump 或 dumpbin
macos+macho	otool

如果未指定此變數，則會透過系統內省自動判斷。

CMAKE_GET_RUNTIME_DEPENDENCIES_COMMAND

決定用於相依性解析的工具路徑。這是 objdump、 dumpbin 或 otool 的實際路徑。

如果未指定此變數，則會透過 CMAKE_OBJDUMP 的值 (如果已設定)，否則透過系統內省判斷。

在 3.18 版本中新增：如果已設定，則使用 CMAKE_OBJDUMP。