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 版本中新增。
指定
.cmake自訂擷取腳本的完整路徑，該腳本由ExternalData_URL_TEMPLATES清單中的項目中的<key>識別。請參閱自訂擷取腳本。
- ExternalData_LINK_CONTENT¶
可以將
ExternalData_LINK_CONTENT變數設定為支援的雜湊演算法的名稱，以啟用自動將DATA{}語法參考的真實資料檔案轉換為內容連結。對於每個此類<file>，都會建立名為<file><ext>的內容連結。原始檔案會重新命名為.ExternalData_<algo>_<hash>的形式，以便在未來傳輸到 URL 範本清單中的其中一個位置（透過此模組範圍之外的方式）。如果使用任何 URL 範本都找不到暫存物件，則為內容連結建立的資料擷取規則將會使用該暫存物件。
- ExternalData_NO_SYMLINKS¶
在 3.3 版本中新增。
在某些平台上，可以使用符號連結在
ExternalData_BINARY_ROOT下提供由展開的DATA{}參考命名的真實資料檔案。可以設定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)。或者，可以使用帶有ExternalData_URL_ALGO_<algo>_<key>變數的%(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 = regex of the form (<number>)(<suffix>)$
對於更複雜的情況，請設定
ExternalData_SERIES_PARSE = regex with at least two () groups
ExternalData_SERIES_PARSE_PREFIX = <prefix> regex group number, if any
ExternalData_SERIES_PARSE_NUMBER = <number> regex group number
ExternalData_SERIES_PARSE_SUFFIX = <suffix> regex group number
使用符合名為 <prefix><number><suffix> 的序列成員的 <number> 部分的正規表示式來設定序列號碼比對
ExternalData_SERIES_MATCH = regex matching <number> in all series members
請注意，序列的 <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> Description
------- ----- -----------
MD5 .md5 Message-Digest Algorithm 5, RFC 1321
SHA1 .sha1 US Secure Hash Algorithm 1, RFC 3174
SHA224 .sha224 US Secure Hash Algorithms, RFC 4634
SHA256 .sha256 US Secure Hash Algorithms, RFC 4634
SHA384 .sha384 US Secure Hash Algorithms, RFC 4634
SHA512 .sha512 US Secure Hash Algorithms, 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¶
當自訂的抓取腳本未能抓取所請求的內容時，它必須將此變數設定為一個簡短的單行訊息，描述失敗的原因。