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> 中。如果命令無法取得時間戳記，變數將設定為空字串 ("")。

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

寫入

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>

僅在條件為真時，才為特定配置產生輸出檔案。在評估產生器表達式後，條件必須為 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 上有意義，在 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 中。

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

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

鎖定由 <path> 指定的檔案，如果沒有 DIRECTORY 選項，則鎖定檔案 <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>

在解析函式庫時，要視為「bundle executable」的可執行檔。在 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 名稱 - 每個正規表示式都必須檢查大寫和小寫字母。例如

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

   將 DLL 名稱轉換為小寫允許正規表示式僅比對小寫名稱，從而簡化了正規表示式。例如

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

   此正規表示式將會比對 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/ 替換為 bundle executable 的目錄會產生現有的檔案，則依賴項會解析為該檔案。

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，則使用此變數。