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 上會被忽略。