CPack External Generator¶
Added in version 3.13.
CPack provides many generators to create packages for a variety of platforms and packaging systems. The intention is for CMake/CPack to be a complete end-to-end solution for building and packaging a software project. However, it may not always be possible to use CPack for the entire packaging process, due to either technical limitations or policies that require the use of certain tools. For this reason, CPack provides the "External" generator, which allows external packaging software to take advantage of some of the functionality provided by CPack, such as component installation and the dependency graph.
Integration with External Packaging Tools¶
The CPack External generator generates a .json file containing the
CPack internal metadata, which gives external software information
on how to package the software. External packaging software may itself
invoke CPack, consume the generated metadata,
install and package files as required.
Alternatively CPack can invoke an external packaging software
through an optional custom CMake script in
CPACK_EXTERNAL_PACKAGE_SCRIPT instead.
Staging of installation files may also optionally be
taken care of by the generator when enabled through the
CPACK_EXTERNAL_ENABLE_STAGING variable.
JSON Format¶
The JSON metadata file contains a list of CPack components and component groups,
the various options passed to cpack_add_component() and
cpack_add_component_group(), the dependencies between the components
and component groups, and various other options passed to CPack.
The JSON's root object will always provide two fields:
formatVersionMajor and formatVersionMinor, which are always integers
that describe the output format of the generator. Backwards-compatible changes
to the output format (for example, adding a new field that didn't exist before)
cause the minor version to be incremented, and backwards-incompatible changes
(for example, deleting a field or changing its meaning) cause the major version
to be incremented and the minor version reset to 0. The format version is
always of the format major.minor. In other words, it always has exactly two
parts, separated by a period.
You can request one or more specific versions of the output format as described
below with CPACK_EXTERNAL_REQUESTED_VERSIONS. The output format will
have a major version that exactly matches the requested major version, and a
minor version that is greater than or equal to the requested minor version. If
no version is requested with CPACK_EXTERNAL_REQUESTED_VERSIONS, the
latest known major version is used by default. Currently, the only supported
format is 1.0, which is described below.
Version 1.0¶
In addition to the standard format fields, format version 1.0 provides the following fields in the root:
componentsThe
componentsfield is an object with component names as the keys and objects describing the components as the values. The component objects have the following fields:nameThe name of the component. This is always the same as the key in the
componentsobject.displayNameThe value of the
DISPLAY_NAMEfield passed tocpack_add_component().descriptionThe value of the
DESCRIPTIONfield passed tocpack_add_component().isHiddenTrue if
HIDDENwas passed tocpack_add_component(), false if it was not.isRequiredTrue if
REQUIREDwas passed tocpack_add_component(), false if it was not.isDisabledByDefaultTrue if
DISABLEDwas passed tocpack_add_component(), false if it was not.groupOnly present if
GROUPwas passed tocpack_add_component(). If so, this field is a string value containing the component's group.dependenciesAn array of components the component depends on. This contains the values in the
DEPENDSargument passed tocpack_add_component(). If noDEPENDSargument was passed, this is an empty list.installationTypesAn array of installation types the component is part of. This contains the values in the
INSTALL_TYPESargument passed tocpack_add_component(). If noINSTALL_TYPESargument was passed, this is an empty list.isDownloadedTrue if
DOWNLOADEDwas passed tocpack_add_component(), false if it was not.archiveFileThe name of the archive file passed with the
ARCHIVE_FILEargument tocpack_add_component(). If noARCHIVE_FILEargument was passed, this is an empty string.
componentGroupsThe
componentGroupsfield is an object with component group names as the keys and objects describing the component groups as the values. The component group objects have the following fields:nameThe name of the component group. This is always the same as the key in the
componentGroupsobject.displayNameThe value of the
DISPLAY_NAMEfield passed tocpack_add_component_group().descriptionThe value of the
DESCRIPTIONfield passed tocpack_add_component_group().parentGroupOnly present if
PARENT_GROUPwas passed tocpack_add_component_group(). If so, this field is a string value containing the component group's parent group.isExpandedByDefaultTrue if
EXPANDEDwas passed tocpack_add_component_group(), false if it was not.isBoldTrue if
BOLD_TITLEwas passed tocpack_add_component_group(), false if it was not.componentsAn array of names of components that are direct members of the group (components that have this group as their
GROUP). Components of subgroups are not included.subgroupsAn array of names of component groups that are subgroups of the group (groups that have this group as their
PARENT_GROUP).
installationTypesThe
installationTypesfield is an object with installation type names as the keys and objects describing the installation types as the values. The installation type objects have the following fields:nameThe name of the installation type. This is always the same as the key in the
installationTypesobject.displayNameThe value of the
DISPLAY_NAMEfield passed tocpack_add_install_type().indexThe integer index of the installation type in the list.
projectsThe
projectsfield is an array of objects describing CMake projects which comprise the CPack project. The values in this field are derived fromCPACK_INSTALL_CMAKE_PROJECTS. In most cases, this will be only a single project. The project objects have the following fields:projectNameThe project name passed to
CPACK_INSTALL_CMAKE_PROJECTS.componentThe name of the component or component set which comprises the project.
directoryThe build directory of the CMake project. This is the directory which contains the
cmake_install.cmakescript.subDirectoryThe subdirectory to install the project into inside the CPack package.
packageNameThe package name given in
CPACK_PACKAGE_NAME. Only present if this option is set.packageVersionThe package version given in
CPACK_PACKAGE_VERSION. Only present if this option is set.packageDescriptionFileThe package description file given in
CPACK_PACKAGE_DESCRIPTION_FILE. Only present if this option is set.packageDescriptionSummaryThe package description summary given in
CPACK_PACKAGE_DESCRIPTION_SUMMARY. Only present if this option is set.buildConfigThe build configuration given to CPack with the
cpack -Coption. Only present if this option is set.defaultDirectoryPermissionsThe default directory permissions given in
CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS. Only present if this option is set.setDestdirTrue if
CPACK_SET_DESTDIRis true, false if it is not.packagingInstallPrefixThe install prefix given in
CPACK_PACKAGING_INSTALL_PREFIX. Only present ifCPACK_SET_DESTDIRis true.stripFilesTrue if
CPACK_STRIP_FILESis true, false if it is not.warnOnAbsoluteInstallDestinationTrue if
CPACK_WARN_ON_ABSOLUTE_INSTALL_DESTINATIONis true, false if it is not.errorOnAbsoluteInstallDestinationTrue if
CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATIONis true, false if it is not.
Variables specific to CPack External generator¶
- CPACK_EXTERNAL_REQUESTED_VERSIONS¶
This variable is used to request a specific version of the CPack External generator. It is a list of
major.minorvalues, separated by semicolons.If this variable is set to a non-empty value, the CPack External generator will iterate through each item in the list to search for a version that it knows how to generate. Requested versions should be listed in order of descending preference by the client software, as the first matching version in the list will be generated.
The generator knows how to generate the version if it has a versioned generator whose major version exactly matches the requested major version, and whose minor version is greater than or equal to the requested minor version. For example, if
CPACK_EXTERNAL_REQUESTED_VERSIONScontains 1.0, and the CPack External generator knows how to generate 1.1, it will generate 1.1. If the generator doesn't know how to generate a version in the list, it skips the version and looks at the next one. If it doesn't know how to generate any of the requested versions, an error is thrown.If this variable is not set, or is empty, the CPack External generator will generate the highest major and minor version that it knows how to generate.
If an invalid version is encountered in
CPACK_EXTERNAL_REQUESTED_VERSIONS(one that doesn't matchmajor.minor, wheremajorandminorare integers), it is ignored.
- CPACK_EXTERNAL_ENABLE_STAGING¶
This variable can be set to true to enable optional installation into a temporary staging area which can then be picked up and packaged by an external packaging tool. The top level directory used by CPack for the current packaging task is contained in
CPACK_TOPLEVEL_DIRECTORY. It is automatically cleaned up on each run before packaging is initiated and can be used for custom temporary files required by the external packaging tool. It also contains the staging areaCPACK_TEMPORARY_DIRECTORYinto which CPack performs the installation when staging is enabled.
- CPACK_EXTERNAL_PACKAGE_SCRIPT¶
This variable can optionally specify the full path to a CMake script file to be run as part of the CPack invocation. It is invoked after (optional) staging took place and may run an external packaging tool. The script has access to the variables defined by the CPack config file.
- CPACK_EXTERNAL_BUILT_PACKAGES¶
Added in version 3.19.
The
CPACK_EXTERNAL_PACKAGE_SCRIPTscript may set this list variable to the full paths of generated package files. CPack will copy these files from the staging directory back to the top build directory and possibly produce checksum files if theCPACK_PACKAGE_CHECKSUMis set.