CPackComponent¶
配置用于二进制安装程序和源包的组件。
简介¶
此模块由 CPack
自动包含。
某些由 CPack 生成的二进制安装程序(尤其是图形安装程序)允许用户选择要安装的单个应用程序组件。此模块允许开发人员配置此类组件的打包。
内容通过 CMake 的 COMPONENT
参数分配给组件,如 install()
命令所定义。可以使用用户友好的名称和描述、组件间依赖关系等注释组件,并以各种方式分组以自定义生成的安装程序,使用下面描述的命令。
要为不同的 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.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 上被忽略。