Help/cpack_gen/external.rst

   1 CPack External Generator
   2 ------------------------
   3
   4 .. versionadded:: 3.13
   5
   6 CPack provides many generators to create packages for a variety of platforms
   7 and packaging systems. The intention is for CMake/CPack to be a complete
   8 end-to-end solution for building and packaging a software project. However, it
   9 may not always be possible to use CPack for the entire packaging process, due
  10 to either technical limitations or policies that require the use of certain
  11 tools. For this reason, CPack provides the "External" generator, which allows
  12 external packaging software to take advantage of some of the functionality
  13 provided by CPack, such as component installation and the dependency graph.
  14
  15 Integration with External Packaging Tools
  16 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  17
  18 The CPack External generator generates a ``.json`` file containing the
  19 CPack internal metadata, which gives external software information
  20 on how to package the software. External packaging software may itself
  21 invoke CPack, consume the generated metadata,
  22 install and package files as required.
  23
  24 Alternatively CPack can invoke an external packaging software
  25 through an optional custom CMake script in
  26 :variable:`CPACK_EXTERNAL_PACKAGE_SCRIPT` instead.
  27
  28 Staging of installation files may also optionally be
  29 taken care of by the generator when enabled through the
  30 :variable:`CPACK_EXTERNAL_ENABLE_STAGING` variable.
  31
  32 JSON Format
  33 ^^^^^^^^^^^
  34
  35 The JSON metadata file contains a list of CPack components and component groups,
  36 the various options passed to :command:`cpack_add_component` and
  37 :command:`cpack_add_component_group`, the dependencies between the components
  38 and component groups, and various other options passed to CPack.
  39
  40 The JSON's root object will always provide two fields:
  41 ``formatVersionMajor`` and ``formatVersionMinor``, which are always integers
  42 that describe the output format of the generator. Backwards-compatible changes
  43 to the output format (for example, adding a new field that didn't exist before)
  44 cause the minor version to be incremented, and backwards-incompatible changes
  45 (for example, deleting a field or changing its meaning) cause the major version
  46 to be incremented and the minor version reset to 0. The format version is
  47 always of the format ``major.minor``. In other words, it always has exactly two
  48 parts, separated by a period.
  49
  50 You can request one or more specific versions of the output format as described
  51 below with :variable:`CPACK_EXTERNAL_REQUESTED_VERSIONS`. The output format will
  52 have a major version that exactly matches the requested major version, and a
  53 minor version that is greater than or equal to the requested minor version. If
  54 no version is requested with :variable:`CPACK_EXTERNAL_REQUESTED_VERSIONS`, the
  55 latest known major version is used by default. Currently, the only supported
  56 format is 1.0, which is described below.
  57
  58 Version 1.0
  59 ***********
  60
  61 In addition to the standard format fields, format version 1.0 provides the
  62 following fields in the root:
  63
  64 ``components``
  65   The ``components`` field is an object with component names as the keys and
  66   objects describing the components as the values. The component objects have
  67   the following fields:
  68
  69   ``name``
  70     The name of the component. This is always the same as the key in the
  71     ``components`` object.
  72
  73   ``displayName``
  74     The value of the ``DISPLAY_NAME`` field passed to
  75     :command:`cpack_add_component`.
  76
  77   ``description``
  78     The value of the ``DESCRIPTION`` field passed to
  79     :command:`cpack_add_component`.
  80
  81   ``isHidden``
  82     True if ``HIDDEN`` was passed to :command:`cpack_add_component`, false if
  83     it was not.
  84
  85   ``isRequired``
  86     True if ``REQUIRED`` was passed to :command:`cpack_add_component`, false if
  87     it was not.
  88
  89   ``isDisabledByDefault``
  90     True if ``DISABLED`` was passed to :command:`cpack_add_component`, false if
  91     it was not.
  92
  93   ``group``
  94     Only present if ``GROUP`` was passed to :command:`cpack_add_component`. If
  95     so, this field is a string value containing the component's group.
  96
  97   ``dependencies``
  98     An array of components the component depends on. This contains the values
  99     in the ``DEPENDS`` argument passed to :command:`cpack_add_component`. If no
 100     ``DEPENDS`` argument was passed, this is an empty list.
 101
 102   ``installationTypes``
 103     An array of installation types the component is part of. This contains the
 104     values in the ``INSTALL_TYPES`` argument passed to
 105     :command:`cpack_add_component`. If no ``INSTALL_TYPES`` argument was
 106     passed, this is an empty list.
 107
 108   ``isDownloaded``
 109     True if ``DOWNLOADED`` was passed to :command:`cpack_add_component`, false
 110     if it was not.
 111
 112   ``archiveFile``
 113     The name of the archive file passed with the ``ARCHIVE_FILE`` argument to
 114     :command:`cpack_add_component`. If no ``ARCHIVE_FILE`` argument was passed,
 115     this is an empty string.
 116
 117 ``componentGroups``
 118   The ``componentGroups`` field is an object with component group names as the
 119   keys and objects describing the component groups as the values. The component
 120   group objects have the following fields:
 121
 122   ``name``
 123     The name of the component group. This is always the same as the key in the
 124     ``componentGroups`` object.
 125
 126   ``displayName``
 127     The value of the ``DISPLAY_NAME`` field passed to
 128     :command:`cpack_add_component_group`.
 129
 130   ``description``
 131     The value of the ``DESCRIPTION`` field passed to
 132     :command:`cpack_add_component_group`.
 133
 134   ``parentGroup``
 135     Only present if ``PARENT_GROUP`` was passed to
 136     :command:`cpack_add_component_group`. If so, this field is a string value
 137     containing the component group's parent group.
 138
 139   ``isExpandedByDefault``
 140     True if ``EXPANDED`` was passed to :command:`cpack_add_component_group`,
 141     false if it was not.
 142
 143   ``isBold``
 144     True if ``BOLD_TITLE`` was passed to :command:`cpack_add_component_group`,
 145     false if it was not.
 146
 147   ``components``
 148     An array of names of components that are direct members of the group
 149     (components that have this group as their ``GROUP``). Components of
 150     subgroups are not included.
 151
 152   ``subgroups``
 153     An array of names of component groups that are subgroups of the group
 154     (groups that have this group as their ``PARENT_GROUP``).
 155
 156 ``installationTypes``
 157   The ``installationTypes`` field is an object with installation type names as
 158   the keys and objects describing the installation types as the values. The
 159   installation type objects have the following fields:
 160
 161   ``name``
 162     The name of the installation type. This is always the same as the key in
 163     the ``installationTypes`` object.
 164
 165   ``displayName``
 166     The value of the ``DISPLAY_NAME`` field passed to
 167     :command:`cpack_add_install_type`.
 168
 169   ``index``
 170     The integer index of the installation type in the list.
 171
 172 ``projects``
 173   The ``projects`` field is an array of objects describing CMake projects which
 174   comprise the CPack project. The values in this field are derived from
 175   :variable:`CPACK_INSTALL_CMAKE_PROJECTS`. In most cases, this will be only a
 176   single project. The project objects have the following fields:
 177
 178   ``projectName``
 179     The project name passed to :variable:`CPACK_INSTALL_CMAKE_PROJECTS`.
 180
 181   ``component``
 182     The name of the component or component set which comprises the project.
 183
 184   ``directory``
 185     The build directory of the CMake project. This is the directory which
 186     contains the ``cmake_install.cmake`` script.
 187
 188   ``subDirectory``
 189     The subdirectory to install the project into inside the CPack package.
 190
 191 ``packageName``
 192   The package name given in :variable:`CPACK_PACKAGE_NAME`. Only present if
 193   this option is set.
 194
 195 ``packageVersion``
 196   The package version given in :variable:`CPACK_PACKAGE_VERSION`. Only present
 197   if this option is set.
 198
 199 ``packageDescriptionFile``
 200   The package description file given in
 201   :variable:`CPACK_PACKAGE_DESCRIPTION_FILE`. Only present if this option is
 202   set.
 203
 204 ``packageDescriptionSummary``
 205   The package description summary given in
 206   :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY`. Only present if this option is
 207   set.
 208
 209 ``buildConfig``
 210   The build configuration given to CPack with the :option:`cpack -C` option.
 211   Only present if this option is set.
 212
 213 ``defaultDirectoryPermissions``
 214   The default directory permissions given in
 215   :variable:`CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS`. Only present if this
 216   option is set.
 217
 218 ``setDestdir``
 219   True if :variable:`CPACK_SET_DESTDIR` is true, false if it is not.
 220
 221 ``packagingInstallPrefix``
 222   The install prefix given in :variable:`CPACK_PACKAGING_INSTALL_PREFIX`. Only
 223   present if :variable:`CPACK_SET_DESTDIR` is true.
 224
 225 ``stripFiles``
 226   True if :variable:`CPACK_STRIP_FILES` is true, false if it is not.
 227
 228 ``warnOnAbsoluteInstallDestination``
 229   True if :variable:`CPACK_WARN_ON_ABSOLUTE_INSTALL_DESTINATION` is true, false
 230   if it is not.
 231
 232 ``errorOnAbsoluteInstallDestination``
 233   True if :variable:`CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION` is true,
 234   false if it is not.
 235
 236 Variables specific to CPack External generator
 237 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 238
 239 .. variable:: CPACK_EXTERNAL_REQUESTED_VERSIONS
 240
 241   This variable is used to request a specific version of the CPack External
 242   generator. It is a list of ``major.minor`` values, separated by semicolons.
 243
 244   If this variable is set to a non-empty value, the CPack External generator
 245   will iterate through each item in the list to search for a version that it
 246   knows how to generate. Requested versions should be listed in order of
 247   descending preference by the client software, as the first matching version
 248   in the list will be generated.
 249
 250   The generator knows how to generate the version if it has a versioned
 251   generator whose major version exactly matches the requested major version,
 252   and whose minor version is greater than or equal to the requested minor
 253   version. For example, if ``CPACK_EXTERNAL_REQUESTED_VERSIONS`` contains 1.0, and
 254   the CPack External generator knows how to generate 1.1, it will generate 1.1.
 255   If the generator doesn't know how to generate a version in the list, it skips
 256   the version and looks at the next one. If it doesn't know how to generate any
 257   of the requested versions, an error is thrown.
 258
 259   If this variable is not set, or is empty, the CPack External generator will
 260   generate the highest major and minor version that it knows how to generate.
 261
 262   If an invalid version is encountered in ``CPACK_EXTERNAL_REQUESTED_VERSIONS`` (one
 263   that doesn't match ``major.minor``, where ``major`` and ``minor`` are
 264   integers), it is ignored.
 265
 266 .. variable:: CPACK_EXTERNAL_ENABLE_STAGING
 267
 268   This variable can be set to true to enable optional installation
 269   into a temporary staging area which can then be picked up
 270   and packaged by an external packaging tool.
 271   The top level directory used by CPack for the current packaging
 272   task is contained in ``CPACK_TOPLEVEL_DIRECTORY``.
 273   It is automatically cleaned up on each run before packaging is initiated
 274   and can be used for custom temporary files required by
 275   the external packaging tool.
 276   It also contains the staging area ``CPACK_TEMPORARY_DIRECTORY``
 277   into which CPack performs the installation when staging is enabled.
 278
 279 .. variable:: CPACK_EXTERNAL_PACKAGE_SCRIPT
 280
 281   This variable can optionally specify the full path to
 282   a CMake script file to be run as part of the CPack invocation.
 283   It is invoked after (optional) staging took place and may
 284   run an external packaging tool. The script has access to
 285   the variables defined by the CPack config file.
 286
 287 .. variable:: CPACK_EXTERNAL_BUILT_PACKAGES
 288
 289   .. versionadded:: 3.19
 290
 291   The ``CPACK_EXTERNAL_PACKAGE_SCRIPT`` script may set this list variable to the
 292   full paths of generated package files.  CPack will copy these files from the
 293   staging directory back to the top build directory and possibly produce
 294   checksum files if the :variable:`CPACK_PACKAGE_CHECKSUM` is set.