CPack 外部產生器

新增於 3.13 版本。

CPack 提供了許多產生器，用於為各種平台和封裝系統建立套件。其目的是讓 CMake/CPack 成為軟體專案建置和封裝的完整端對端解決方案。然而，由於技術限制或需要使用特定工具的政策，可能無法總是使用 CPack 來完成整個封裝過程。因此，CPack 提供了「外部」產生器，允許外部封裝軟體利用 CPack 提供的一些功能，例如組件安裝和依賴圖。

與外部封裝工具整合

CPack 外部產生器會產生一個 .json 檔案，其中包含 CPack 內部中繼資料，為外部軟體提供如何封裝軟體的資訊。外部封裝軟體可以自行調用 CPack、使用產生的中繼資料、安裝和封裝所需檔案。

或者，CPack 可以透過 CPACK_EXTERNAL_PACKAGE_SCRIPT 中可選的自訂 CMake 腳本來調用外部封裝軟體。

當透過 CPACK_EXTERNAL_ENABLE_STAGING 變數啟用時，安裝檔案的暫存也可以由產生器選擇性地處理。

JSON 格式

JSON 中繼資料檔案包含 CPack 組件和組件群組的清單、傳遞給 cpack_add_component() 和 cpack_add_component_group() 的各種選項、組件和組件群組之間的依賴關係，以及傳遞給 CPack 的各種其他選項。

JSON 的根物件始終提供兩個欄位：formatVersionMajor 和 formatVersionMinor，它們始終是整數，描述產生器的輸出格式。對輸出格式的向後相容變更（例如，新增之前不存在的新欄位）會導致次要版本遞增，而向後不相容的變更（例如，刪除欄位或變更其含義）會導致主要版本遞增，而次要版本重設為 0。格式版本始終為 major.minor 格式。換句話說，它始終只有兩個部分，並以句點分隔。

您可以使用 CPACK_EXTERNAL_REQUESTED_VERSIONS 來請求一個或多個特定的輸出格式版本，如下所述。輸出格式的主要版本將與請求的主要版本完全匹配，而次要版本將大於或等於請求的次要版本。如果沒有使用 CPACK_EXTERNAL_REQUESTED_VERSIONS 請求版本，則預設會使用最新的已知主要版本。目前，唯一支援的格式是 1.0，如下所述。

版本 1.0

除了標準格式欄位之外，格式版本 1.0 在根目錄中提供以下欄位

組件

components 欄位是一個物件，其中組件名稱作為鍵，而描述組件的物件作為值。組件物件具有以下欄位

名稱

組件的名稱。這始終與 components 物件中的鍵相同。

顯示名稱

傳遞給 cpack_add_component() 的 DISPLAY_NAME 欄位的值。

描述

傳遞給 cpack_add_component() 的 DESCRIPTION 欄位的值。

isHidden

如果將 HIDDEN 傳遞給 cpack_add_component()，則為 True，否則為 False。

isRequired

如果將 REQUIRED 傳遞給 cpack_add_component()，則為 True，否則為 False。

isDisabledByDefault

如果將 DISABLED 傳遞給 cpack_add_component()，則為 True，否則為 False。

群組

僅當將 GROUP 傳遞給 cpack_add_component() 時才會出現。如果有的話，此欄位是一個字串值，其中包含組件的群組。

依賴關係

組件所依賴的組件陣列。其中包含傳遞給 cpack_add_component() 的 DEPENDS 引數中的值。如果沒有傳遞 DEPENDS 引數，則這是一個空清單。

安裝類型

組件所屬的安裝類型陣列。其中包含傳遞給 cpack_add_component() 的 INSTALL_TYPES 引數中的值。如果沒有傳遞 INSTALL_TYPES 引數，則這是一個空清單。

已下載

如果將 DOWNLOADED 傳遞給 cpack_add_component()，則為 True，否則為 False。

封存檔

使用 ARCHIVE_FILE 引數傳遞給 cpack_add_component() 的封存檔案名稱。如果沒有傳遞 ARCHIVE_FILE 引數，則這是一個空字串。

組件群組

componentGroups 欄位是一個物件，其中組件群組名稱作為鍵，而描述組件群組的物件作為值。組件群組物件具有以下欄位

名稱

組件群組的名稱。這始終與 componentGroups 物件中的鍵相同。

顯示名稱

傳遞給 cpack_add_component_group() 的 DISPLAY_NAME 欄位的值。

描述

傳遞給 cpack_add_component_group() 的 DESCRIPTION 欄位的值。

父群組

僅當將 PARENT_GROUP 傳遞給 cpack_add_component_group() 時才會出現。如果有的話，此欄位是一個字串值，其中包含組件群組的父群組。

isExpandedByDefault

如果將 EXPANDED 傳遞給 cpack_add_component_group()，則為 True，否則為 False。

isBold

如果 BOLD_TITLE 傳遞給 cpack_add_component_group()，則為 True，否則為 False。

組件

直接屬於該群組的元件名稱陣列（將此群組作為其 GROUP 的元件）。不包含子群組的元件。

子群組

屬於該群組的子群組的元件群組名稱陣列（將此群組作為其 PARENT_GROUP 的群組）。

安裝類型

installationTypes 欄位是一個物件，以安裝類型名稱作為鍵，並以描述安裝類型的物件作為值。安裝類型物件具有以下欄位：

名稱

安裝類型的名稱。這始終與 installationTypes 物件中的鍵相同。

顯示名稱

傳遞給 cpack_add_install_type() 的 DISPLAY_NAME 欄位的值。

索引

安裝類型在列表中的整數索引。

專案

projects 欄位是一個物件陣列，描述構成 CPack 專案的 CMake 專案。此欄位中的值來自 CPACK_INSTALL_CMAKE_PROJECTS。在大多數情況下，這只會有一個專案。專案物件具有以下欄位：

projectName

傳遞給 CPACK_INSTALL_CMAKE_PROJECTS 的專案名稱。

元件

構成該專案的元件或元件集合的名稱。

目錄

CMake 專案的建置目錄。這是包含 cmake_install.cmake 指令碼的目錄。

子目錄

將專案安裝到 CPack 套件中的子目錄。

packageName

在 CPACK_PACKAGE_NAME 中指定的套件名稱。僅當設定此選項時才會出現。

packageVersion

在 CPACK_PACKAGE_VERSION 中指定的套件版本。僅當設定此選項時才會出現。

packageDescriptionFile

在 CPACK_PACKAGE_DESCRIPTION_FILE 中指定的套件描述檔案。僅當設定此選項時才會出現。

packageDescriptionSummary

在 CPACK_PACKAGE_DESCRIPTION_SUMMARY 中指定的套件描述摘要。僅當設定此選項時才會出現。

buildConfig

透過 cpack -C 選項提供給 CPack 的建置組態。僅當設定此選項時才會出現。

defaultDirectoryPermissions

在 CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS 中指定的預設目錄權限。僅當設定此選項時才會出現。

setDestdir

如果 CPACK_SET_DESTDIR 為 true，則為 True，否則為 False。

packagingInstallPrefix

在 CPACK_PACKAGING_INSTALL_PREFIX 中指定的安裝前綴。僅當 CPACK_SET_DESTDIR 為 true 時才會出現。

stripFiles

如果 CPACK_STRIP_FILES 為 true，則為 True，否則為 False。

warnOnAbsoluteInstallDestination

如果 CPACK_WARN_ON_ABSOLUTE_INSTALL_DESTINATION 為 true，則為 True，否則為 False。

errorOnAbsoluteInstallDestination

如果 CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION 為 true，則為 True，否則為 False。

CPack External 產生器特定的變數

CPACK_EXTERNAL_REQUESTED_VERSIONS

此變數用於請求 CPack External 產生器的特定版本。它是由分號分隔的 major.minor 值列表。

如果此變數設定為非空值，CPack External 產生器將迭代列表中的每個項目，以搜尋它知道如何產生的版本。請求的版本應按照客戶端軟體的降序偏好順序列出，因為將產生列表中第一個符合的版本。

如果產生器具有主要版本與請求的主要版本完全匹配，並且次要版本大於或等於請求的次要版本的版本化產生器，則該產生器知道如何產生該版本。例如，如果 CPACK_EXTERNAL_REQUESTED_VERSIONS 包含 1.0，並且 CPack External 產生器知道如何產生 1.1，它將產生 1.1。如果產生器不知道如何產生列表中的版本，它會跳過該版本並查看下一個版本。如果它不知道如何產生任何請求的版本，則會擲回錯誤。

如果未設定此變數或為空，CPack External 產生器將產生它知道如何產生的最高主要和次要版本。

如果在 CPACK_EXTERNAL_REQUESTED_VERSIONS 中遇到無效版本（不符合 major.minor 的版本，其中 major 和 minor 是整數），則會忽略它。

CPACK_EXTERNAL_ENABLE_STAGING

可以將此變數設定為 true，以啟用可選安裝到臨時暫存區域中，然後可以由外部封裝工具選取並封裝。CPack 用於目前封裝任務的頂層目錄包含在 CPACK_TOPLEVEL_DIRECTORY 中。它會在每次執行時在啟動封裝之前自動清除，並且可以用於外部封裝工具所需的自訂臨時檔案。它還包含暫存區域 CPACK_TEMPORARY_DIRECTORY，當啟用暫存時，CPack 會在其中執行安裝。

CPACK_EXTERNAL_PACKAGE_SCRIPT

此變數可以選擇性地指定要作為 CPack 調用一部分執行的 CMake 指令碼檔案的完整路徑。它會在（可選）暫存發生後調用，並且可以執行外部封裝工具。該指令碼可以存取 CPack 組態檔案定義的變數。

CPACK_EXTERNAL_BUILT_PACKAGES

在 3.19 版中新增。

CPACK_EXTERNAL_PACKAGE_SCRIPT 指令碼可以將此列表變數設定為產生的套件檔案的完整路徑。如果設定了 CPACK_PACKAGE_CHECKSUM，CPack 會將這些檔案從暫存目錄複製回頂層建置目錄，並可能產生檢查總和檔案。