1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
|
CPack External Generator
------------------------
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.
The CPack External generator doesn't actually package any files. Instead, it
generates a .json file containing the CPack internal metadata, which gives
external software information on how to package the software. This metadata
file contains a list of CPack components and component groups, the various
options passed to :command:`cpack_add_component` and
:command:`cpack_add_component_group`, the dependencies between the components
and component groups, and various other options passed to CPack.
Format
^^^^^^
The file produced by the CPack External generator is a .json file with an
object as its root. This 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 :variable:`CPACK_EXT_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 :variable:`CPACK_EXT_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:
``components``
The ``components`` field is an object with component names as the keys and
objects describing the components as the values. The component objects have
the following fields:
``name``
The name of the component. This is always the same as the key in the
``components`` object.
``displayName``
The value of the ``DISPLAY_NAME`` field passed to
:command:`cpack_add_component`.
``description``
The value of the ``DESCRIPTION`` field passed to
:command:`cpack_add_component`.
``isHidden``
True if ``HIDDEN`` was passed to :command:`cpack_add_component`, false if
it was not.
``isRequired``
True if ``REQUIRED`` was passed to :command:`cpack_add_component`, false if
it was not.
``isDisabledByDefault``
True if ``DISABLED`` was passed to :command:`cpack_add_component`, false if
it was not.
``group``
Only present if ``GROUP`` was passed to :command:`cpack_add_component`. If
so, this field is a string value containing the component's group.
``dependencies``
An array of components the component depends on. This contains the values
in the ``DEPENDS`` argument passed to :command:`cpack_add_component`. If no
``DEPENDS`` argument was passed, this is an empty list.
``installationTypes``
An array of installation types the component is part of. This contains the
values in the ``INSTALL_TYPES`` argument passed to
:command:`cpack_add_component`. If no ``INSTALL_TYPES`` argument was
passed, this is an empty list.
``isDownloaded``
True if ``DOWNLOADED`` was passed to :command:`cpack_add_component`, false
if it was not.
``archiveFile``
The name of the archive file passed with the ``ARCHIVE_FILE`` argument to
:command:`cpack_add_component`. If no ``ARCHIVE_FILE`` argument was passed,
this is an empty string.
``componentGroups``
The ``componentGroups`` field 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:
``name``
The name of the component group. This is always the same as the key in the
``componentGroups`` object.
``displayName``
The value of the ``DISPLAY_NAME`` field passed to
:command:`cpack_add_component_group`.
``description``
The value of the ``DESCRIPTION`` field passed to
:command:`cpack_add_component_group`.
``parentGroup``
Only present if ``PARENT_GROUP`` was passed to
:command:`cpack_add_component_group`. If so, this field is a string value
containing the component group's parent group.
``isExpandedByDefault``
True if ``EXPANDED`` was passed to :command:`cpack_add_component_group`,
false if it was not.
``isBold``
True if ``BOLD_TITLE`` was passed to :command:`cpack_add_component_group`,
false if it was not.
``components``
An 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.
``subgroups``
An array of names of component groups that are subgroups of the group
(groups that have this group as their ``PARENT_GROUP``).
``installationTypes``
The ``installationTypes`` field 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:
``name``
The name of the installation type. This is always the same as the key in
the ``installationTypes`` object.
``displayName``
The value of the ``DISPLAY_NAME`` field passed to
:command:`cpack_add_install_type`.
``index``
The integer index of the installation type in the list.
``projects``
The ``projects`` field is an array of objects describing CMake projects which
comprise the CPack project. The values in this field are derived from
:variable:`CPACK_INSTALL_CMAKE_PROJECTS`. In most cases, this will be only a
single project. The project objects have the following fields:
``projectName``
The project name passed to :variable:`CPACK_INSTALL_CMAKE_PROJECTS`.
``component``
The name of the component or component set which comprises the project.
``directory``
The build directory of the CMake project. This is the directory which
contains the ``cmake_install.cmake`` script.
``subDirectory``
The subdirectory to install the project into inside the CPack package.
``packageName``
The package name given in :variable:`CPACK_PACKAGE_NAME`. Only present if
this option is set.
``packageVersion``
The package version given in :variable:`CPACK_PACKAGE_VERSION`. Only present
if this option is set.
``packageDescriptionFile``
The package description file given in
:variable:`CPACK_PACKAGE_DESCRIPTION_FILE`. Only present if this option is
set.
``packageDescriptionSummary``
The package description summary given in
:variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY`. Only present if this option is
set.
``buildConfig``
The build configuration given to CPack with the ``-C`` option. Only present
if this option is set.
``defaultDirectoryPermissions``
The default directory permissions given in
:variable:`CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS`. Only present if this
option is set.
``setDestdir``
True if :variable:`CPACK_SET_DESTDIR` is true, false if it is not.
``packagingInstallPrefix``
The install prefix given in :variable:`CPACK_PACKAGING_INSTALL_PREFIX`. Only
present if :variable:`CPACK_SET_DESTDIR` is true.
``stripFiles``
True if :variable:`CPACK_STRIP_FILES` is true, false if it is not.
``warnOnAbsoluteInstallDestination``
True if :variable:`CPACK_WARN_ON_ABSOLUTE_INSTALL_DESTINATION` is true, false
if it is not.
``errorOnAbsoluteInstallDestination``
True if :variable:`CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION` is true,
false if it is not.
Variables specific to CPack External generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. variable:: CPACK_EXT_REQUESTED_VERSIONS
This variable is used to request a specific version of the CPack External
generator. It is a list of ``major.minor`` values, 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_EXT_REQUESTED_VERSIONS`` contains 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_EXT_REQUESTED_VERSIONS`` (one
that doesn't match ``major.minor``, where ``major`` and ``minor`` are
integers), it is ignored.
|
