1 CPack External Generator
2 ------------------------
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.
15 Integration with External Packaging Tools
16 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
24 Alternatively CPack can invoke an external packaging software
25 through an optional custom CMake script in
26 :variable:`CPACK_EXTERNAL_PACKAGE_SCRIPT` instead.
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.
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.
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.
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.
61 In addition to the standard format fields, format version 1.0 provides the
62 following fields in the root:
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
70 The name of the component. This is always the same as the key in the
71 ``components`` object.
74 The value of the ``DISPLAY_NAME`` field passed to
75 :command:`cpack_add_component`.
78 The value of the ``DESCRIPTION`` field passed to
79 :command:`cpack_add_component`.
82 True if ``HIDDEN`` was passed to :command:`cpack_add_component`, false if
86 True if ``REQUIRED`` was passed to :command:`cpack_add_component`, false if
89 ``isDisabledByDefault``
90 True if ``DISABLED`` was passed to :command:`cpack_add_component`, false if
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.
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.
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.
109 True if ``DOWNLOADED`` was passed to :command:`cpack_add_component`, false
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.
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:
123 The name of the component group. This is always the same as the key in the
124 ``componentGroups`` object.
127 The value of the ``DISPLAY_NAME`` field passed to
128 :command:`cpack_add_component_group`.
131 The value of the ``DESCRIPTION`` field passed to
132 :command:`cpack_add_component_group`.
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.
139 ``isExpandedByDefault``
140 True if ``EXPANDED`` was passed to :command:`cpack_add_component_group`,
144 True if ``BOLD_TITLE`` was passed to :command:`cpack_add_component_group`,
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.
153 An array of names of component groups that are subgroups of the group
154 (groups that have this group as their ``PARENT_GROUP``).
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:
162 The name of the installation type. This is always the same as the key in
163 the ``installationTypes`` object.
166 The value of the ``DISPLAY_NAME`` field passed to
167 :command:`cpack_add_install_type`.
170 The integer index of the installation type in the list.
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:
179 The project name passed to :variable:`CPACK_INSTALL_CMAKE_PROJECTS`.
182 The name of the component or component set which comprises the project.
185 The build directory of the CMake project. This is the directory which
186 contains the ``cmake_install.cmake`` script.
189 The subdirectory to install the project into inside the CPack package.
192 The package name given in :variable:`CPACK_PACKAGE_NAME`. Only present if
196 The package version given in :variable:`CPACK_PACKAGE_VERSION`. Only present
197 if this option is set.
199 ``packageDescriptionFile``
200 The package description file given in
201 :variable:`CPACK_PACKAGE_DESCRIPTION_FILE`. Only present if this option is
204 ``packageDescriptionSummary``
205 The package description summary given in
206 :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY`. Only present if this option is
210 The build configuration given to CPack with the ``-C`` option. Only present
211 if this option is set.
213 ``defaultDirectoryPermissions``
214 The default directory permissions given in
215 :variable:`CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS`. Only present if this
219 True if :variable:`CPACK_SET_DESTDIR` is true, false if it is not.
221 ``packagingInstallPrefix``
222 The install prefix given in :variable:`CPACK_PACKAGING_INSTALL_PREFIX`. Only
223 present if :variable:`CPACK_SET_DESTDIR` is true.
226 True if :variable:`CPACK_STRIP_FILES` is true, false if it is not.
228 ``warnOnAbsoluteInstallDestination``
229 True if :variable:`CPACK_WARN_ON_ABSOLUTE_INSTALL_DESTINATION` is true, false
232 ``errorOnAbsoluteInstallDestination``
233 True if :variable:`CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION` is true,
236 Variables specific to CPack External generator
237 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
239 .. variable:: CPACK_EXTERNAL_REQUESTED_VERSIONS
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.
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.
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.
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.
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.
266 .. variable:: CPACK_EXTERNAL_ENABLE_STAGING
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.
279 .. variable:: CPACK_EXTERNAL_PACKAGE_SCRIPT
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.
287 .. variable:: CPACK_EXTERNAL_BUILT_PACKAGES
289 .. versionadded:: 3.19
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.