1CPack External Generator
2------------------------
3
4.. versionadded:: 3.13
5
6CPack provides many generators to create packages for a variety of platforms
7and packaging systems. The intention is for CMake/CPack to be a complete
8end-to-end solution for building and packaging a software project. However, it
9may not always be possible to use CPack for the entire packaging process, due
10to either technical limitations or policies that require the use of certain
11tools. For this reason, CPack provides the "External" generator, which allows
12external packaging software to take advantage of some of the functionality
13provided by CPack, such as component installation and the dependency graph.
14
15Integration with External Packaging Tools
16^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
17
18The CPack External generator generates a ``.json`` file containing the
19CPack internal metadata, which gives external software information
20on how to package the software. External packaging software may itself
21invoke CPack, consume the generated metadata,
22install and package files as required.
23
24Alternatively CPack can invoke an external packaging software
25through an optional custom CMake script in
26:variable:`CPACK_EXTERNAL_PACKAGE_SCRIPT` instead.
27
28Staging of installation files may also optionally be
29taken care of by the generator when enabled through the
30:variable:`CPACK_EXTERNAL_ENABLE_STAGING` variable.
31
32JSON Format
33^^^^^^^^^^^
34
35The JSON metadata file contains a list of CPack components and component groups,
36the various options passed to :command:`cpack_add_component` and
37:command:`cpack_add_component_group`, the dependencies between the components
38and component groups, and various other options passed to CPack.
39
40The JSON's root object will always provide two fields:
41``formatVersionMajor`` and ``formatVersionMinor``, which are always integers
42that describe the output format of the generator. Backwards-compatible changes
43to the output format (for example, adding a new field that didn't exist before)
44cause the minor version to be incremented, and backwards-incompatible changes
45(for example, deleting a field or changing its meaning) cause the major version
46to be incremented and the minor version reset to 0. The format version is
47always of the format ``major.minor``. In other words, it always has exactly two
48parts, separated by a period.
49
50You can request one or more specific versions of the output format as described
51below with :variable:`CPACK_EXTERNAL_REQUESTED_VERSIONS`. The output format will
52have a major version that exactly matches the requested major version, and a
53minor version that is greater than or equal to the requested minor version. If
54no version is requested with :variable:`CPACK_EXTERNAL_REQUESTED_VERSIONS`, the
55latest known major version is used by default. Currently, the only supported
56format is 1.0, which is described below.
57
58Version 1.0
59***********
60
61In addition to the standard format fields, format version 1.0 provides the
62following 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 ``-C`` option. Only present
211  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
236Variables 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.
295