CPackComponent ¶

此模块提供用于配置二进制安装程序和源程序包组件的命令。

在 CMake 项目中加载此模块，使用

include(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。

命令 (Commands)¶

添加组件 ¶

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 生成器时传递给 pkgbuild 的 --component-plist 参数的文件名。

添加组件组 ¶

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.com.cn/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 上会被忽略。