CPackComponent ¶

為二進位安裝程式和原始碼套件配置組件。

簡介 ¶

此模組由 CPack 自動包含。

某些由 CPack 產生的二進位安裝程式（尤其是圖形安裝程式）允許使用者選擇個別應用程式組件進行安裝。此模組允許開發人員配置此類組件的封裝。

內容會透過 CMake install() 命令的 COMPONENT 參數指派給組件。可以使用以下描述的命令，使用使用者友善的名稱和描述、組件間的依賴關係等註解組件，並以各種方式分組以自訂產生的安裝程式。

若要為不同的 CPack 產生器指定不同的分組，請使用 CPACK_PROJECT_CONFIG_FILE。

變數 ¶

以下變數會影響組件特定的封裝

CPACK_COMPONENTS_ALL¶

要安裝的組件清單。

此變數的預設值由 CPack 計算，並包含專案定義的所有組件。使用者可以設定它僅包含指定的組件。

除了指定所有想要的組件外，還可以取得所有已定義組件的清單，然後從清單中移除不需要的組件。get_cmake_property() 命令可用於取得 COMPONENTS 屬性，然後 list(REMOVE_ITEM) 命令可用於移除不需要的組件。例如，要使用除 foo 和 bar 之外的所有已定義組件

get_cmake_property(CPACK_COMPONENTS_ALL COMPONENTS)
list(REMOVE_ITEM CPACK_COMPONENTS_ALL "foo" "bar")

CPACK_<GENNAME>_COMPONENT_INSTALL¶

為 CPack 產生器 <GENNAME> 啟用/停用組件安裝。

每個 CPack 產生器（RPM、DEB、ARCHIVE、NSIS、DMG 等...）都有舊版的預設行為。例如，RPM 建置單體式，而 NSIS 建置組件。可以透過將此變數設定為 0/1 或 OFF/ON 來變更預設行為。

CPACK_COMPONENTS_GROUPING¶

指定如何為多套件組件感知 CPack 產生器分組組件。

某些產生器（例如 RPM 或 ARCHIVE (TGZ, ZIP, ...)）在有組件時可能會產生多個套件檔案，具體取決於此變數的值

ONE_PER_GROUP（預設）：每個組件群組建立一個套件
IGNORE：每個組件建立一個套件（忽略群組）
ALL_COMPONENTS_IN_ONE：建立包含所有請求組件的單一套件

CPACK_COMPONENT_<compName>_DISPLAY_NAME¶: 要為組件顯示的名稱。

CPACK_COMPONENT_<compName>_DESCRIPTION¶: 組件的描述。

CPACK_COMPONENT_<compName>_GROUP¶: 組件的群組。

CPACK_COMPONENT_<compName>_DEPENDS¶: 此組件依賴的依賴項（組件清單）。

CPACK_COMPONENT_<compName>_HIDDEN¶: 如果此組件對使用者隱藏，則為 True。

CPACK_COMPONENT_<compName>_REQUIRED¶: 如果此組件是必要的，則為 True。

CPACK_COMPONENT_<compName>_DISABLED¶: 如果預設情況下未選取此組件進行安裝，則為 True。

命令 ¶

新增組件 ¶

cpack_add_component¶

描述安裝組件。

cpack_add_component(compname
                    [DISPLAY_NAME name]
                    [DESCRIPTION description]
                    [HIDDEN | REQUIRED | DISABLED ]
                    [GROUP group]
                    [DEPENDS comp1 comp2 ... ]
                    [INSTALL_TYPES type1 type2 ... ]
                    [DOWNLOADED]
                    [ARCHIVE_FILE filename]
                    [PLIST filename])

compname 是安裝組件的名稱，由一個或多個 CMake install() 命令的 COMPONENT 參數定義。透過 cpack_add_component 命令，可以設定安裝組件的名稱、描述和其他屬性。也可以將組件指派給組件群組。

DISPLAY_NAME 是組件的顯示名稱，用於圖形安裝程式中顯示組件名稱。此值可以是任何字串。

DESCRIPTION 是組件的擴充描述，用於圖形安裝程式中，向使用者提供有關組件的其他資訊。描述可以使用 \n 作為行分隔符號跨越多行。通常，這些描述不應超過幾行。

HIDDEN 指示此組件將在圖形安裝程式中隱藏，以便使用者無法直接變更是否安裝它。

REQUIRED 指示此組件是必要的，因此將始終安裝。它將在圖形安裝程式中可見，但無法取消選取。（通常，必要的組件會顯示為灰色）。

DISABLED 指示預設情況下應停用（取消選取）此組件。使用者可以自由選取此組件進行安裝，除非它也是 HIDDEN。

DEPENDS 列出此組件依賴的組件。如果選取此組件，則也必須選取列出的每個組件。依賴關係資訊編碼在安裝程式本身中，以便使用者無法安裝不一致的組件集。

GROUP 命名此組件所屬的組件群組。如果未提供，則組件將是獨立組件，而不是任何組件群組的一部分。組件群組在 cpack_add_component_group 命令中描述，詳述如下。

INSTALL_TYPES 列出此組件所屬的安裝類型。當選取其中一個安裝類型時，將自動選取此組件。安裝類型在 cpack_add_install_type 命令中描述，詳述如下。

DOWNLOADED 指示此組件應由安裝程式即時下載，而不是與安裝程式本身一起封裝。有關更多資訊，請參閱 cpack_configure_downloads 命令。

ARCHIVE_FILE 為 CPack 建立的封存檔提供名稱，以用於下載的組件。如果未提供，CPack 將建立一個檔案，其名稱基於 CPACK_PACKAGE_FILE_NAME 和組件的名稱。有關更多資訊，請參閱 cpack_configure_downloads。

PLIST 提供一個檔案名稱，在使用 productbuild 產生器時，會使用 --component-plist 參數傳遞給 pkgbuild。

新增組件群組 ¶

cpack_add_component_group¶

描述相關的 CPack 安裝組件群組。

cpack_add_component_group(groupname
                         [DISPLAY_NAME name]
                         [DESCRIPTION description]
                         [PARENT_GROUP parent]
                         [EXPANDED]
                         [BOLD_TITLE])

cpack_add_component_group 描述了一組安裝組件，這些組件將一起放置在選項列表中。通常，組件群組允許使用者透過單一群組層級選項選取/取消選取單一群組內的所有組件。使用組件群組來降低具有許多選項的安裝程式的複雜性。groupname 是用於識別 cpack_add_component 命令的 GROUP 參數中群組的任意名稱，用於將組件放置在群組中。群組的名稱不得與任何組件的名稱衝突。

DISPLAY_NAME 是組件群組的顯示名稱，用於圖形安裝程式中顯示組件群組名稱。此值可以是任何字串。

DESCRIPTION 是組件群組的擴充描述，用於圖形安裝程式中，向使用者提供有關該群組內組件的其他資訊。描述可以使用 \n 作為行分隔符號跨越多行。通常，這些描述不應超過幾行。

PARENT_GROUP（如果提供）命名此群組的父群組。父群組用於建立群組的階層結構，提供群組的任意階層結構。

EXPANDED 指示預設情況下，群組應顯示為「展開」，以便使用者立即看到群組內的所有組件。否則，群組最初將顯示為單個條目。

BOLD_TITLE 指示群組標題應以粗體顯示，以引起使用者對群組的注意。

新增安裝類型 ¶

cpack_add_install_type¶

新增一個新的安裝類型，其中包含一組預定義的組件選擇到圖形安裝程式。

cpack_add_install_type(typename
                       [DISPLAY_NAME name])

cpack_add_install_type 命令識別一組預先選取的組件，這些組件代表應用程式的常見使用案例。例如，「開發人員」安裝類型可能包含應用程式及其標頭和程式庫檔案，而「終端使用者」安裝類型可能僅包含應用程式的可執行檔。每個組件透過 cpack_add_component 的 INSTALL_TYPES 參數識別自身與一個或多個安裝類型。

DISPLAY_NAME 是安裝類型的顯示名稱，通常會顯示在圖形安裝程式內的下拉式方塊中。此值可以是任何字串。

配置下載 ¶

cpack_configure_downloads¶

配置 CPack 以在安裝過程中即時下載選定的組件。

cpack_configure_downloads(site
                          [UPLOAD_DIRECTORY dirname]
                          [ALL]
                          [ADD_REMOVE|NO_ADD_REMOVE])

cpack_configure_downloads 命令配置選定組件的安裝時下載。對於每個可下載的組件，CPack 將建立一個封存檔，其中包含該組件的內容，應將其上傳到給定的站點。當使用者選取該組件進行安裝時，安裝程式將下載並就地解壓縮組件。此功能對於建立僅下載請求組件的小型安裝程式非常有用，可節省頻寬。此外，安裝程式夠小，可以作為正常安裝過程的一部分安裝，並且 Windows「新增/移除程式」控制面板中的「變更」按鈕將允許在原始安裝後新增或移除應用程式的部件。在 Windows 上，下載組件功能需要 NSIS 的 ZipDLL 外掛程式，可在以下網址取得

http://nsis.sourceforge.net/ZipDLL_plug-in

在 macOS 上，即時下載組件的安裝程式只能在使用 macOS 10.5 或更高版本的系統上建置和安裝。

site 參數是可下載組件的封存檔所在的 URL，例如 https://cmake.dev.org.tw/files/v3.25/。CPack 產生的所有封存檔都應上傳到該位置。

UPLOAD_DIRECTORY 是 CPack 將為每個組件建立各種封存檔的本機目錄。此目錄的內容應上傳到可透過 site 參數中給定的 URL 存取的位置。如果省略，CPack 將使用 CMake 二進位目錄內的 CPackUploads 目錄來儲存產生的封存檔。

ALL 旗標指示應下載所有組件。否則，僅下載明確標記為 DOWNLOADED 或具有指定 ARCHIVE_FILE 的組件。此外，ALL 選項暗示 ADD_REMOVE（除非指定 NO_ADD_REMOVE）。

ADD_REMOVE 指示 CPack 應安裝安裝程式的副本，可以從 Windows 的「新增/移除程式」對話方塊（透過「修改」按鈕）呼叫該副本，以變更已安裝組件的集合。NO_ADD_REMOVE 關閉此行為。此選項在 Mac OS X 上會被忽略。