1CPack IFW Generator
2-------------------
3
4.. versionadded:: 3.1
5
6Configure and run the Qt Installer Framework to generate a Qt installer.
7
8.. only:: html
9
10  .. contents::
11
12Overview
13^^^^^^^^
14
15This :manual:`cpack generator <cpack-generators(7)>` generates
16configuration and meta information for the `Qt Installer Framework
17<http://doc.qt.io/qtinstallerframework/index.html>`_ (QtIFW),
18and runs QtIFW tools to generate a Qt installer.
19
20QtIFW provides tools and utilities to create installers for
21the platforms supported by `Qt <https://www.qt.io>`_: Linux,
22Microsoft Windows, and macOS.
23
24To make use of this generator, QtIFW needs to be installed.
25The :module:`CPackIFW` module looks for the location of the
26QtIFW command-line utilities, and defines several commands to
27control the behavior of this generator.
28
29Variables
30^^^^^^^^^
31
32You can use the following variables to change behavior of CPack ``IFW``
33generator.
34
35Debug
36"""""
37
38.. variable:: CPACK_IFW_VERBOSE
39
40 .. versionadded:: 3.3
41
42 Set to ``ON`` to enable addition debug output.
43 By default is ``OFF``.
44
45Package
46"""""""
47
48.. variable:: CPACK_IFW_PACKAGE_TITLE
49
50 Name of the installer as displayed on the title bar.
51 By default used :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY`.
52
53.. variable:: CPACK_IFW_PACKAGE_PUBLISHER
54
55 Publisher of the software (as shown in the Windows Control Panel).
56 By default used :variable:`CPACK_PACKAGE_VENDOR`.
57
58.. variable:: CPACK_IFW_PRODUCT_URL
59
60 URL to a page that contains product information on your web site.
61
62.. variable:: CPACK_IFW_PACKAGE_ICON
63
64 Filename for a custom installer icon. The actual file is '.icns' (macOS),
65 '.ico' (Windows). No functionality on Unix.
66
67.. variable:: CPACK_IFW_PACKAGE_WINDOW_ICON
68
69 Filename for a custom window icon in PNG format for the Installer
70 application.
71
72.. variable:: CPACK_IFW_PACKAGE_LOGO
73
74 Filename for a logo is used as QWizard::LogoPixmap.
75
76.. variable:: CPACK_IFW_PACKAGE_WATERMARK
77
78 .. versionadded:: 3.8
79
80 Filename for a watermark is used as QWizard::WatermarkPixmap.
81
82.. variable:: CPACK_IFW_PACKAGE_BANNER
83
84 .. versionadded:: 3.8
85
86 Filename for a banner is used as QWizard::BannerPixmap.
87
88.. variable:: CPACK_IFW_PACKAGE_BACKGROUND
89
90 .. versionadded:: 3.8
91
92 Filename for an image used as QWizard::BackgroundPixmap (only used by MacStyle).
93
94.. variable:: CPACK_IFW_PACKAGE_WIZARD_STYLE
95
96 .. versionadded:: 3.8
97
98 Wizard style to be used ("Modern", "Mac", "Aero" or "Classic").
99
100.. variable:: CPACK_IFW_PACKAGE_WIZARD_DEFAULT_WIDTH
101
102 .. versionadded:: 3.8
103
104 Default width of the wizard in pixels. Setting a banner image will override this.
105
106.. variable:: CPACK_IFW_PACKAGE_WIZARD_DEFAULT_HEIGHT
107
108 .. versionadded:: 3.8
109
110 Default height of the wizard in pixels. Setting a watermark image will override this.
111
112.. variable:: CPACK_IFW_PACKAGE_WIZARD_SHOW_PAGE_LIST
113
114 .. versionadded:: 3.20
115
116 Set to ``OFF`` if the widget listing installer pages on the left side of the wizard should not be shown.
117
118 It is ``ON`` by default, but will only have an effect if using QtIFW 4.0 or later.
119
120.. variable:: CPACK_IFW_PACKAGE_TITLE_COLOR
121
122 .. versionadded:: 3.8
123
124 Color of the titles and subtitles (takes an HTML color code, such as "#88FF33").
125
126.. variable:: CPACK_IFW_PACKAGE_STYLE_SHEET
127
128 .. versionadded:: 3.15
129
130 Filename for a stylesheet.
131
132.. variable:: CPACK_IFW_TARGET_DIRECTORY
133
134 Default target directory for installation.
135 By default used
136 "@ApplicationsDir@/:variable:`CPACK_PACKAGE_INSTALL_DIRECTORY`"
137 (variables embedded in '@' are expanded by the
138 `QtIFW scripting engine <https://doc.qt.io/qtinstallerframework/scripting.html>`_).
139
140 You can use predefined variables.
141
142.. variable:: CPACK_IFW_ADMIN_TARGET_DIRECTORY
143
144 Default target directory for installation with administrator rights.
145
146 You can use predefined variables.
147
148.. variable:: CPACK_IFW_PACKAGE_REMOVE_TARGET_DIR
149
150 .. versionadded:: 3.11
151
152 Set to ``OFF`` if the target directory should not be deleted when uninstalling.
153
154 Is ``ON`` by default
155
156.. variable:: CPACK_IFW_PACKAGE_GROUP
157
158 The group, which will be used to configure the root package
159
160.. variable:: CPACK_IFW_PACKAGE_NAME
161
162 The root package name, which will be used if configuration group is not
163 specified
164
165.. variable:: CPACK_IFW_PACKAGE_START_MENU_DIRECTORY
166
167 .. versionadded:: 3.3
168
169 Name of the default program group for the product in the Windows Start menu.
170
171 By default used :variable:`CPACK_IFW_PACKAGE_NAME`.
172
173.. variable:: CPACK_IFW_PACKAGE_MAINTENANCE_TOOL_NAME
174
175 .. versionadded:: 3.3
176
177 Filename of the generated maintenance tool.
178 The platform-specific executable file extension is appended.
179
180 By default used QtIFW defaults (``maintenancetool``).
181
182.. variable:: CPACK_IFW_PACKAGE_MAINTENANCE_TOOL_INI_FILE
183
184 .. versionadded:: 3.3
185
186 Filename for the configuration of the generated maintenance tool.
187
188 By default used QtIFW defaults (``maintenancetool.ini``).
189
190.. variable:: CPACK_IFW_PACKAGE_ALLOW_NON_ASCII_CHARACTERS
191
192 .. versionadded:: 3.3
193
194 Set to ``ON`` if the installation path can contain non-ASCII characters.
195
196 Is ``ON`` for QtIFW less 2.0 tools.
197
198.. variable:: CPACK_IFW_PACKAGE_ALLOW_SPACE_IN_PATH
199
200 .. versionadded:: 3.3
201
202 Set to ``OFF`` if the installation path cannot contain space characters.
203
204 Is ``ON`` for QtIFW less 2.0 tools.
205
206.. variable:: CPACK_IFW_PACKAGE_CONTROL_SCRIPT
207
208 .. versionadded:: 3.3
209
210 Filename for a custom installer control script.
211
212.. variable:: CPACK_IFW_PACKAGE_RESOURCES
213
214 .. versionadded:: 3.7
215
216 List of additional resources ('.qrc' files) to include in the installer
217 binary.
218
219 You can use :command:`cpack_ifw_add_package_resources` command to resolve
220 relative paths.
221
222.. variable:: CPACK_IFW_PACKAGE_FILE_EXTENSION
223
224 .. versionadded:: 3.10
225
226 The target binary extension.
227
228 On Linux, the name of the target binary is automatically extended with
229 '.run', if you do not specify the extension.
230
231 On Windows, the target is created as an application with the extension
232 '.exe', which is automatically added, if not supplied.
233
234 On Mac, the target is created as an DMG disk image with the extension
235 '.dmg', which is automatically added, if not supplied.
236
237.. variable:: CPACK_IFW_REPOSITORIES_ALL
238
239 The list of remote repositories.
240
241 The default value of this variable is computed by CPack and contains
242 all repositories added with command :command:`cpack_ifw_add_repository`
243 or updated with command :command:`cpack_ifw_update_repository`.
244
245.. variable:: CPACK_IFW_DOWNLOAD_ALL
246
247 If this is ``ON`` all components will be downloaded.
248 By default is ``OFF`` or used value
249 from ``CPACK_DOWNLOAD_ALL`` if set
250
251Components
252""""""""""
253
254.. variable:: CPACK_IFW_RESOLVE_DUPLICATE_NAMES
255
256 Resolve duplicate names when installing components with groups.
257
258.. variable:: CPACK_IFW_PACKAGES_DIRECTORIES
259
260 Additional prepared packages dirs that will be used to resolve
261 dependent components.
262
263.. variable:: CPACK_IFW_REPOSITORIES_DIRECTORIES
264
265 .. versionadded:: 3.10
266
267 Additional prepared repository dirs that will be used to resolve and
268 repack dependent components. This feature available only
269 since QtIFW 3.1.
270
271QtIFW Tools
272"""""""""""
273
274.. variable:: CPACK_IFW_FRAMEWORK_VERSION
275
276 .. versionadded:: 3.3
277
278 The version of used QtIFW tools.
279
280The following variables provide the locations of the QtIFW
281command-line tools as discovered by the module :module:`CPackIFW`.
282These variables are cached, and may be configured if needed.
283
284.. variable:: CPACK_IFW_ARCHIVEGEN_EXECUTABLE
285
286 .. versionadded:: 3.19
287
288 The path to ``archivegen``.
289
290.. variable:: CPACK_IFW_BINARYCREATOR_EXECUTABLE
291
292 The path to ``binarycreator``.
293
294.. variable:: CPACK_IFW_REPOGEN_EXECUTABLE
295
296 The path to ``repogen``.
297
298.. variable:: CPACK_IFW_INSTALLERBASE_EXECUTABLE
299
300 The path to ``installerbase``.
301
302.. variable:: CPACK_IFW_DEVTOOL_EXECUTABLE
303
304 The path to ``devtool``.
305
306Hints for Finding QtIFW
307"""""""""""""""""""""""
308
309Generally, the CPack ``IFW`` generator automatically finds QtIFW tools,
310but if you don't use a default path for installation of the QtIFW tools,
311the path may be specified in either a CMake or an environment variable:
312
313.. variable:: CPACK_IFW_ROOT
314
315 .. versionadded:: 3.9
316
317 An CMake variable which specifies the location of the QtIFW tool suite.
318
319 The variable will be cached in the ``CPackConfig.cmake`` file and used at
320 CPack runtime.
321
322.. variable:: QTIFWDIR
323
324 An environment variable which specifies the location of the QtIFW tool
325 suite.
326
327.. note::
328  The specified path should not contain "bin" at the end
329  (for example: "D:\\DevTools\\QtIFW2.0.5").
330
331The :variable:`CPACK_IFW_ROOT` variable has a higher priority and overrides
332the value of the :variable:`QTIFWDIR` variable.
333
334Other Settings
335^^^^^^^^^^^^^^
336
337Online installer
338""""""""""""""""
339
340By default, this generator generates an *offline installer*. This means that
341that all packaged files are fully contained in the installer executable.
342
343In contrast, an *online installer* will download some or all components from
344a remote server.
345
346The ``DOWNLOADED`` option in the :command:`cpack_add_component` command
347specifies that a component is to be downloaded. Alternatively, the ``ALL``
348option in the :command:`cpack_configure_downloads` command specifies that
349`all` components are to be be downloaded.
350
351The :command:`cpack_ifw_add_repository` command and the
352:variable:`CPACK_IFW_DOWNLOAD_ALL` variable allow for more specific
353configuration.
354
355When there are online components, CPack will write them to archive files.
356The help page of the :module:`CPackComponent` module, especially the section
357on the :command:`cpack_configure_downloads` function, explains how to make
358these files accessible from a download URL.
359
360Internationalization
361""""""""""""""""""""
362
363.. versionadded:: 3.9
364
365Some variables and command arguments support internationalization via
366CMake script. This is an optional feature.
367
368Installers created by QtIFW tools have built-in support for
369internationalization and many phrases are localized to many languages,
370but this does not apply to the description of the your components and groups
371that will be distributed.
372
373Localization of the description of your components and groups is useful for
374users of your installers.
375
376A localized variable or argument can contain a single default value, and a
377set of pairs the name of the locale and the localized value.
378
379For example:
380
381.. code-block:: cmake
382
383   set(LOCALIZABLE_VARIABLE "Default value"
384     en "English value"
385     en_US "American value"
386     en_GB "Great Britain value"
387     )
388
389See Also
390^^^^^^^^
391
392Qt Installer Framework Manual:
393
394* Index page:
395  http://doc.qt.io/qtinstallerframework/index.html
396
397* Component Scripting:
398  http://doc.qt.io/qtinstallerframework/scripting.html
399
400* Predefined Variables:
401  http://doc.qt.io/qtinstallerframework/scripting.html#predefined-variables
402
403* Promoting Updates:
404  http://doc.qt.io/qtinstallerframework/ifw-updates.html
405
406Download Qt Installer Framework for your platform from Qt site:
407 http://download.qt.io/official_releases/qt-installer-framework
408