ExternalData

管理儲存在來源樹狀結構外的資料檔案

簡介

使用此模組來明確參考儲存在來源樹狀結構外的資料檔案，並在建置時從任意本機和遠端內容定址位置提取它們。此模組提供的函式會辨識語法為 DATA{<name>} 的引數作為外部資料的參考，將它們替換為這些資料本機副本的完整路徑，並建立建置規則來提取和更新本機副本。

例如

include(ExternalData)
set(ExternalData_URL_TEMPLATES "file:///local/%(algo)/%(hash)"
                               "file:////host/share/%(algo)/%(hash)"
                               "http://data.org/%(algo)/%(hash)")
ExternalData_Add_Test(MyData
  NAME MyTest
  COMMAND MyExe DATA{MyInput.png}
  )
ExternalData_Add_Target(MyData)

當測試 MyTest 執行時，DATA{MyInput.png} 引數將被替換為磁碟上資料檔案 MyInput.png 實際例項的完整路徑。如果來源樹狀結構包含內容連結（例如 MyInput.png.md5），則 MyData 目標會在建置樹狀結構中建立一個真實的 MyInput.png。

模組函式

ExternalData_Expand_Arguments

ExternalData_Expand_Arguments 函式會評估其引數中的 DATA{} 參考，並建構一個新的引數列表

ExternalData_Expand_Arguments(
  <target>   # Name of data management target
  <outVar>   # Output variable
  [args...]  # Input arguments, DATA{} allowed
  )

它將引數中的每個 DATA{} 參考替換為 <target> 建置後將存在的真實資料檔案的完整路徑。

ExternalData_Add_Test

ExternalData_Add_Test 函式包裝了 CMake add_test() 命令，但支援其引數中的 DATA{} 參考

ExternalData_Add_Test(
  <target>   # Name of data management target
  ...        # Arguments of add_test(), DATA{} allowed
  )

它將其引數透過 ExternalData_Expand_Arguments 傳遞，然後使用結果調用 add_test() 命令。

變更於版本 3.31：如果 <target> 之後的引數定義了一個具有可執行檔的測試，而該可執行檔是 CMake 目標，則該目標的 TEST_LAUNCHER 和 CROSSCOMPILING_EMULATOR 屬性中的空值將被保留。請參閱政策 CMP0178。

ExternalData_Add_Target

ExternalData_Add_Target 函式建立一個自訂目標來管理外部儲存的資料檔案的本機例項

ExternalData_Add_Target(
  <target>                  # Name of data management target
  [SHOW_PROGRESS <ON|OFF>]  # Show progress during the download
  )

它在目標中建立必要的自訂命令，以使每個先前由此模組提供的其他函式評估的 DATA{} 參考可用的資料檔案。資料檔案可以從 ExternalData_URL_TEMPLATES 變數中指定的 URL 範本之一提取，也可以在本機 ExternalData_OBJECT_STORES 變數中指定的路徑之一中找到。

新增於版本 3.20：可以傳遞 SHOW_PROGRESS 引數來抑制物件下載期間的進度資訊。如果未提供，則對於 Ninja 和 Ninja Multi-Config 產生器，預設值為 OFF，否則為 ON。

通常只需要一個目標來管理專案中的所有外部資料。在所有資料參考都已處理完畢後，在組態結束時呼叫此函式一次。

模組變數

以下變數配置行為。它們應在呼叫此模組提供的任何函式之前設定。

ExternalData_BINARY_ROOT

ExternalData_BINARY_ROOT 變數可以設定為保存由展開的 DATA{} 參考命名的真實資料檔案的目錄。預設值為 CMAKE_BINARY_DIR。目錄佈局將反映 ExternalData_SOURCE_ROOT 下內容連結的佈局。

ExternalData_CUSTOM_SCRIPT_<key>

新增於版本 3.2。

指定 ExternalData_URL_TEMPLATES 列表中條目中由 <key> 識別的 .cmake 自訂提取腳本的完整路徑。請參閱自訂提取腳本。

ExternalData_HTTPHEADERS

新增於版本 4.0。

ExternalData_HTTPHEADERS 變數可用於提供標頭列表，每個元素包含一個格式為 Key: Value 的標頭。請參閱 file(DOWNLOAD) 命令的 HTTPHEADER 選項。

ExternalData_LINK_CONTENT

ExternalData_LINK_CONTENT 變數可以設定為支援的雜湊演算法的名稱，以啟用自動轉換由 DATA{} 語法參考的真實資料檔案為內容連結。對於每個這樣的 <file>，都會建立一個名為 <file><ext> 的內容連結。原始檔案會重新命名為 .ExternalData_<algo>_<hash> 的形式，以便將其暫存以供將來傳輸到 URL 範本列表中的位置之一（透過此模組範圍之外的方式）。為內容連結建立的資料提取規則將使用暫存物件，如果使用任何 URL 範本都找不到該物件。

ExternalData_NO_SYMLINKS

新增於版本 3.3。

由展開的 DATA{} 參考命名的真實資料檔案可以在某些平台上使用符號連結在 ExternalData_BINARY_ROOT 下使用。ExternalData_NO_SYMLINKS 變數可以設定為停用符號連結的使用，並啟用改用副本。

ExternalData_OBJECT_STORES

ExternalData_OBJECT_STORES 變數可以設定為本機目錄的列表，這些目錄使用 <dir>/%(algo)/%(hash) 佈局儲存物件。將首先在這些目錄中搜尋所需的物件。如果物件在任何儲存區中都不可用，則將使用 URL 範本從遠端提取物件，並將其新增到列出的第一個本機儲存區。如果未指定任何儲存區，則預設位置是建置樹狀結構內的某個位置。

ExternalData_SERIES_PARSE

ExternalData_SERIES_PARSE_PREFIX

ExternalData_SERIES_PARSE_NUMBER

ExternalData_SERIES_PARSE_SUFFIX

ExternalData_SERIES_MATCH

請參閱參考檔案序列。

ExternalData_SOURCE_ROOT

ExternalData_SOURCE_ROOT 變數可以設定為包含任何由 DATA{} 參考命名的路徑的最高來源目錄。預設值為 CMAKE_SOURCE_DIR。ExternalData_SOURCE_ROOT 和 CMAKE_SOURCE_DIR 必須參考單個來源發行版中的目錄（例如，它們一起在一個 tarball 中）。

ExternalData_TIMEOUT_ABSOLUTE

ExternalData_TIMEOUT_ABSOLUTE 變數設定下載絕對逾時，以秒為單位，預設值為 300 秒。設定為 0 以停用強制執行。

ExternalData_TIMEOUT_INACTIVITY

ExternalData_TIMEOUT_INACTIVITY 變數設定下載閒置逾時，以秒為單位，預設值為 60 秒。設定為 0 以停用強制執行。

ExternalData_URL_ALGO_<algo>_<key>

新增於版本 3.3。

指定一個自訂 URL 組件，用於替換 %(algo:<key>) 形式的 URL 範本佔位符，其中 <key> 是有效的 C 識別符，用於提取透過雜湊演算法 <algo> 參考的物件。如果未定義，則對於任何 <key>，預設 URL 組件僅為 <algo>。

ExternalData_URL_TEMPLATES

ExternalData_URL_TEMPLATES 可以設定為提供 URL 範本列表，每個範本都使用佔位符 %(algo) 和 %(hash)。資料提取規則會依序嘗試每個 URL 範本，方法是將雜湊演算法名稱替換為 %(algo)，並將雜湊值替換為 %(hash)。或者，可以使用 %(algo:<key>) 和 ExternalData_URL_ALGO_<algo>_<key> 變數來獲得遠端 URL 的更大彈性。

參考檔案

參考單一檔案

DATA{} 語法是字面的，<name> 是來源樹狀結構內的完整或相對路徑。來源樹狀結構必須在 <name> 處包含真實資料檔案，或在 <name><ext> 處包含「內容連結」，其中包含使用對應於 <ext> 的雜湊演算法的真實檔案的雜湊值。例如，引數 DATA{img.png} 可以透過目前來源目錄中的真實 img.png 檔案或包含其 MD5 總和的 img.png.md5 檔案來滿足。

新增於版本 3.8：支援具有相同名稱但不同雜湊演算法的多個內容連結（例如 img.png.sha256 和 img.png.sha1），只要它們都對應於相同的真實檔案。這允許從由不同雜湊演算法索引的來源提取物件。

參考檔案序列

可以告知 DATA{} 語法使用 DATA{<name>,:} 的形式提取檔案序列，其中 : 是字面的。如果來源樹狀結構包含一組檔案或內容連結，其名稱類似於序列，則對其中一個成員的參考會新增規則以提取所有成員。雖然提取了序列的所有成員，但只有最初由 DATA{} 引數命名的檔案會被替換。預設組態會辨識以 #.ext、_#.ext、.#.ext 或 -#.ext 結尾的檔案序列名稱，其中 # 是一系列十進制數字，而 .ext 是任何單個擴展名。使用正則表達式進行配置，該正則表達式從 <name> 的末尾解析 <number> 和 <suffix> 部分

ExternalData_SERIES_PARSE - 形式為 (<number>)(<suffix>)$ 的正則表達式。

對於更複雜的情況，請設定

• ExternalData_SERIES_PARSE - 至少有兩個 () 群組的正則表達式。

• ExternalData_SERIES_PARSE_PREFIX - <prefix> 的正則表達式群組編號（如果有的話）。

• ExternalData_SERIES_PARSE_NUMBER - <number> 的正則表達式群組編號。

• ExternalData_SERIES_PARSE_SUFFIX - <suffix> 的正則表達式群組編號。

使用正則表達式配置序列號碼匹配，該正則表達式匹配名為 <prefix><number><suffix> 的所有序列成員中的 <number> 部分

ExternalData_SERIES_MATCH - 匹配所有序列成員中 <number> 的正則表達式

請注意，序列的 <suffix> 不包含雜湊演算法擴展名。

參考關聯檔案

DATA{} 語法也可以匹配與命名檔案關聯且包含在同一目錄中的檔案。關聯檔案可以透過使用語法 DATA{<name>,<opt1>,<opt2>,...} 的選項來指定。每個選項可以透過名稱指定一個檔案，或使用語法 REGEX:<regex> 指定正則表達式來匹配檔案名稱。例如，引數

DATA{MyData/MyInput.mhd,MyInput.img}                   # File pair
DATA{MyData/MyFrames00.png,REGEX:MyFrames[0-9]+\\.png} # Series

將在命令列上傳遞 MyInput.mha 和 MyFrames00.png，但確保關聯檔案存在於它們旁邊。

參考目錄

DATA{} 語法可以使用尾部斜線和關聯檔案列表來參考目錄。形式 DATA{<name>/,<opt1>,<opt2>,...} 新增規則以提取目錄中與其中一個關聯檔案選項匹配的任何檔案。例如，引數 DATA{MyDataDir/,REGEX:.*} 將在命令列上傳遞 MyDataDir 目錄的完整路徑，並確保該目錄包含與 MyDataDir 來源目錄中的每個檔案或內容連結相對應的檔案。

新增於版本 3.3：為了匹配子目錄中的關聯檔案，請指定 RECURSE: 選項，例如 DATA{MyDataDir/,RECURSE:,REGEX:.*}。

雜湊演算法

支援以下雜湊演算法

%(algo)	<ext>	描述
MD5	.md5	訊息摘要演算法 5，RFC 1321
SHA1	.sha1	美國安全雜湊演算法 1，RFC 3174
SHA224	.sha224	美國安全雜湊演算法，RFC 4634
SHA256	.sha256	美國安全雜湊演算法，RFC 4634
SHA384	.sha384	美國安全雜湊演算法，RFC 4634
SHA512	.sha512	美國安全雜湊演算法，RFC 4634
SHA3_224	.sha3-224	Keccak SHA-3
SHA3_256	.sha3-256	Keccak SHA-3
SHA3_384	.sha3-384	Keccak SHA-3
SHA3_512	.sha3-512	Keccak SHA-3

新增於版本 3.8：新增了 SHA3_* 雜湊演算法。

請注意，雜湊僅用於唯一資料識別和下載驗證。

自訂提取腳本

新增於版本 3.2。

當必須從 ExternalData_URL_TEMPLATES 變數中指定的 URL 範本之一提取資料檔案時，通常會使用 file(DOWNLOAD) 命令下載。可以透過使用 ExternalDataCustomScript://<key>/<loc> 形式的 URL 範本來指定自訂提取腳本的使用。<key> 必須是 C 識別符，而 <loc> 必須包含 %(algo) 和 %(hash) 佔位符。對應於金鑰的變數 ExternalData_CUSTOM_SCRIPT_<key> 必須設定為 .cmake 腳本檔案的完整路徑。腳本將被包含以執行實際提取，並提供以下變數

ExternalData_CUSTOM_LOCATION

載入自訂提取腳本時，此變數會設定為 URL 的位置部分，其中將包含替換的雜湊演算法名稱和內容雜湊值。

ExternalData_CUSTOM_FILE

載入自訂提取腳本時，此變數會設定為腳本必須在其中儲存提取內容的檔案的完整路徑。檔案名稱未指定，不應以任何方式解釋。

預期自訂提取腳本會將提取的內容儲存在檔案中或設定變數

ExternalData_CUSTOM_ERROR

當自訂提取腳本無法提取請求的內容時，它必須將此變數設定為描述失敗原因的簡短單行訊息。