summaryrefslogtreecommitdiffstats
path: root/Help/cpack_gen/ifw.rst
diff options
context:
space:
mode:
authorCraig Scott <craig.scott@crascit.com>2022-03-25 11:40:27 (GMT)
committerCraig Scott <craig.scott@crascit.com>2022-03-27 05:30:45 (GMT)
commitdb774e9108782148fc9c0a2dd701f88dbd32a7d5 (patch)
treea70a3ea3422d4b1326db83ff655514c460b4bdb4 /Help/cpack_gen/ifw.rst
parent18b02cc127730e3b007c2b56c6e115d476f0d5e0 (diff)
downloadCMake-db774e9108782148fc9c0a2dd701f88dbd32a7d5.zip
CMake-db774e9108782148fc9c0a2dd701f88dbd32a7d5.tar.gz
CMake-db774e9108782148fc9c0a2dd701f88dbd32a7d5.tar.bz2
Help: Clean up and expand CPack/IFW docs
Diffstat (limited to 'Help/cpack_gen/ifw.rst')
-rw-r--r--Help/cpack_gen/ifw.rst223
1 files changed, 122 insertions, 101 deletions
diff --git a/Help/cpack_gen/ifw.rst b/Help/cpack_gen/ifw.rst
index a293a16..c23bab4 100644
--- a/Help/cpack_gen/ifw.rst
+++ b/Help/cpack_gen/ifw.rst
@@ -24,12 +24,12 @@ Microsoft Windows, and macOS.
To make use of this generator, QtIFW needs to be installed.
The :module:`CPackIFW` module looks for the location of the
QtIFW command-line utilities, and defines several commands to
-control the behavior of this generator.
+control the behavior of this generator. See `Hints for Finding QtIFW`_.
Variables
^^^^^^^^^
-You can use the following variables to change behavior of CPack ``IFW``
+You can use the following variables to change the behavior of the CPack ``IFW``
generator.
Debug
@@ -48,12 +48,12 @@ Package
.. variable:: CPACK_IFW_PACKAGE_TITLE
Name of the installer as displayed on the title bar.
- By default used :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY`.
+ If not specified, it defaults to :variable:`CPACK_PACKAGE_DESCRIPTION_SUMMARY`.
.. variable:: CPACK_IFW_PACKAGE_PUBLISHER
Publisher of the software (as shown in the Windows Control Panel).
- By default used :variable:`CPACK_PACKAGE_VENDOR`.
+ If not specified, it defaults to :variable:`CPACK_PACKAGE_VENDOR`.
.. variable:: CPACK_IFW_PRODUCT_URL
@@ -61,83 +61,93 @@ Package
.. variable:: CPACK_IFW_PACKAGE_ICON
- Filename for a custom installer icon. The actual file is '.icns' (macOS),
- '.ico' (Windows). No functionality on Unix.
+ Filename for a custom installer icon. It must be an absolute path.
+ This should be a ``.icns`` file on macOS and a ``.ico`` file on Windows.
+ It is ignored on other platforms.
.. variable:: CPACK_IFW_PACKAGE_WINDOW_ICON
Filename for a custom window icon in PNG format for the Installer
- application.
+ application. It must be an absolute path.
.. variable:: CPACK_IFW_PACKAGE_LOGO
- Filename for a logo is used as QWizard::LogoPixmap.
+ Filename for a logo image in PNG format, used as ``QWizard::LogoPixmap``.
+ It must be an absolute path.
.. variable:: CPACK_IFW_PACKAGE_WATERMARK
.. versionadded:: 3.8
- Filename for a watermark is used as QWizard::WatermarkPixmap.
+ Filename for a watermark image in PNG format, used as
+ ``QWizard::WatermarkPixmap``. It must be an absolute path.
.. variable:: CPACK_IFW_PACKAGE_BANNER
.. versionadded:: 3.8
- Filename for a banner is used as QWizard::BannerPixmap.
+ Filename for a banner image in PNG format, used as ``QWizard::BannerPixmap``.
+ It must be an absolute path.
.. variable:: CPACK_IFW_PACKAGE_BACKGROUND
.. versionadded:: 3.8
- Filename for an image used as QWizard::BackgroundPixmap (only used by MacStyle).
+ Filename for a background image in PNG format, used as
+ ``QWizard::BackgroundPixmap`` (only used by ``MacStyle``). It must be an
+ absolute path.
.. variable:: CPACK_IFW_PACKAGE_WIZARD_STYLE
.. versionadded:: 3.8
- Wizard style to be used ("Modern", "Mac", "Aero" or "Classic").
+ Wizard style to be used (``Modern``, ``Mac``, ``Aero`` or ``Classic``).
.. variable:: CPACK_IFW_PACKAGE_WIZARD_DEFAULT_WIDTH
.. versionadded:: 3.8
- Default width of the wizard in pixels. Setting a banner image will override this.
+ Default width of the wizard in pixels. Setting a banner image will override
+ this.
.. variable:: CPACK_IFW_PACKAGE_WIZARD_DEFAULT_HEIGHT
.. versionadded:: 3.8
- Default height of the wizard in pixels. Setting a watermark image will override this.
+ Default height of the wizard in pixels. Setting a watermark image will
+ override this.
.. variable:: CPACK_IFW_PACKAGE_WIZARD_SHOW_PAGE_LIST
.. versionadded:: 3.20
- Set to ``OFF`` if the widget listing installer pages on the left side of the wizard should not be shown.
+ Set to ``OFF`` if the widget listing installer pages on the left side of the
+ wizard should not be shown.
- It is ``ON`` by default, but will only have an effect if using QtIFW 4.0 or later.
+ It is ``ON`` by default, but will only have an effect if using QtIFW 4.0 or
+ later.
.. variable:: CPACK_IFW_PACKAGE_TITLE_COLOR
.. versionadded:: 3.8
- Color of the titles and subtitles (takes an HTML color code, such as "#88FF33").
+ Color of the titles and subtitles (takes an HTML color code, such as
+ ``#88FF33``).
.. variable:: CPACK_IFW_PACKAGE_STYLE_SHEET
.. versionadded:: 3.15
- Filename for a stylesheet.
+ Filename for a stylesheet. It must be an absolute path.
.. variable:: CPACK_IFW_TARGET_DIRECTORY
Default target directory for installation.
- By default used
- "@ApplicationsDir@/:variable:`CPACK_PACKAGE_INSTALL_DIRECTORY`"
- (variables embedded in '@' are expanded by the
- `QtIFW scripting engine <https://doc.qt.io/qtinstallerframework/scripting.html>`_).
-
- You can use predefined variables.
+ If :variable:`CPACK_PACKAGE_INSTALL_DIRECTORY` is set, this defaults to
+ ``@ApplicationsDir@/${CPACK_PACKAGE_INSTALL_DIRECTORY}``. If that variable
+ isn't set either, the default used is ``@RootDir@/usr/local``.
+ Predefined variables of the form ``@...@`` are expanded by the
+ `QtIFW scripting engine <https://doc.qt.io/qtinstallerframework/scripting.html>`_.
.. variable:: CPACK_IFW_ADMIN_TARGET_DIRECTORY
@@ -155,29 +165,28 @@ Package
.. variable:: CPACK_IFW_PACKAGE_GROUP
- The group, which will be used to configure the root package
+ The group, which will be used to configure the root package.
.. variable:: CPACK_IFW_PACKAGE_NAME
- The root package name, which will be used if configuration group is not
- specified
+ The root package name, which will be used if the configuration group is not
+ specified.
.. variable:: CPACK_IFW_PACKAGE_START_MENU_DIRECTORY
.. versionadded:: 3.3
Name of the default program group for the product in the Windows Start menu.
-
- By default used :variable:`CPACK_IFW_PACKAGE_NAME`.
+ If not specified, it defaults to :variable:`CPACK_IFW_PACKAGE_NAME`.
.. variable:: CPACK_IFW_PACKAGE_MAINTENANCE_TOOL_NAME
.. versionadded:: 3.3
Filename of the generated maintenance tool.
- The platform-specific executable file extension is appended.
+ The platform-specific executable file extension will be appended.
- By default used QtIFW defaults (``maintenancetool``).
+ If not specified, QtIFW provides a default name (``maintenancetool``).
.. variable:: CPACK_IFW_PACKAGE_MAINTENANCE_TOOL_INI_FILE
@@ -185,23 +194,15 @@ Package
Filename for the configuration of the generated maintenance tool.
- By default used QtIFW defaults (``maintenancetool.ini``).
+ If not specified, QtIFW uses a default file name (``maintenancetool.ini``).
.. variable:: CPACK_IFW_PACKAGE_ALLOW_NON_ASCII_CHARACTERS
.. versionadded:: 3.3
Set to ``ON`` if the installation path can contain non-ASCII characters.
-
- Is ``ON`` for QtIFW less 2.0 tools.
-
-.. variable:: CPACK_IFW_PACKAGE_DISABLE_COMMAND_LINE_INTERFACE
-
- .. versionadded:: 3.23
-
- Set to ``ON`` if command line interface features should be disabled.
-
- Is ``OFF`` by default, but will only have an effect if using QtIFW 4.0 or later.
+ Only supported for QtIFW 2.0 and later. Older QtIFW versions will always
+ allow non-ASCII characters.
.. variable:: CPACK_IFW_PACKAGE_ALLOW_SPACE_IN_PATH
@@ -211,6 +212,14 @@ Package
Is ``ON`` for QtIFW less 2.0 tools.
+.. variable:: CPACK_IFW_PACKAGE_DISABLE_COMMAND_LINE_INTERFACE
+
+ .. versionadded:: 3.23
+
+ Set to ``ON`` if command line interface features should be disabled.
+ It is ``OFF`` by default and will only have an effect if using QtIFW 4.0 or
+ later.
+
.. variable:: CPACK_IFW_PACKAGE_CONTROL_SCRIPT
.. versionadded:: 3.3
@@ -221,10 +230,11 @@ Package
.. versionadded:: 3.7
- List of additional resources ('.qrc' files) to include in the installer
- binary.
+ List of additional resources (``.qrc`` files) to include in the installer
+ binary. They should be specified as absolute paths and no two resource files
+ can have the same file name.
- You can use :command:`cpack_ifw_add_package_resources` command to resolve
+ You can use the :command:`cpack_ifw_add_package_resources` command to resolve
relative paths.
.. variable:: CPACK_IFW_PACKAGE_FILE_EXTENSION
@@ -234,44 +244,47 @@ Package
The target binary extension.
On Linux, the name of the target binary is automatically extended with
- '.run', if you do not specify the extension.
+ ``.run``, if you do not specify the extension.
On Windows, the target is created as an application with the extension
- '.exe', which is automatically added, if not supplied.
+ ``.exe``, which is automatically added, if not supplied.
On Mac, the target is created as an DMG disk image with the extension
- '.dmg', which is automatically added, if not supplied.
+ ``.dmg``, which is automatically added, if not supplied.
.. variable:: CPACK_IFW_REPOSITORIES_ALL
The list of remote repositories.
The default value of this variable is computed by CPack and contains
- all repositories added with command :command:`cpack_ifw_add_repository`
- or updated with command :command:`cpack_ifw_update_repository`.
+ all repositories added with :command:`cpack_ifw_add_repository`
+ or updated with :command:`cpack_ifw_update_repository`.
.. variable:: CPACK_IFW_DOWNLOAD_ALL
- If this is ``ON`` all components will be downloaded.
- By default is ``OFF`` or used value
- from ``CPACK_DOWNLOAD_ALL`` if set
+ If this is ``ON``, all components will be downloaded. If not set, the
+ behavior is determined by whether :command:`cpack_configure_downloads` has
+ been called with the ``ALL`` option or not.
.. variable:: CPACK_IFW_PACKAGE_PRODUCT_IMAGES
.. versionadded:: 3.23
- A list of images to be shown on the ``PerformInstallationPage``.
+ A list of images to be shown on the ``PerformInstallationPage``. These
+ must be absolute paths and the images must be in PNG format.
- This feature is available for QtIFW 4.0.0 or newer.
+ This feature is available for QtIFW 4.0.0 and later.
.. variable:: CPACK_IFW_PACKAGE_RUN_PROGRAM
.. versionadded:: 3.23
- Command executed after the installer is done if the user accepts the action.
- Provide the full path to the application.
+ Command executed after the installer is finished, if the user accepts the
+ action. Provide the full path to the application, as found when installed.
+ This typically means the path should begin with the QtIFW predefined variable
+ ``@TargetDir@``.
- This feature is available for QtIFW 4.0.0 and newer.
+ This feature is available for QtIFW 4.0.0 and later.
.. variable:: CPACK_IFW_PACKAGE_RUN_PROGRAM_ARGUMENTS
@@ -280,7 +293,7 @@ Package
List of arguments passed to the program specified in
:variable:`CPACK_IFW_PACKAGE_RUN_PROGRAM`.
- This feature is available for QtIFW 4.0.0 and newer.
+ This feature is available for QtIFW 4.0.0 and later.
.. variable:: CPACK_IFW_PACKAGE_RUN_PROGRAM_DESCRIPTION
@@ -288,16 +301,17 @@ Package
Text shown next to the check box for running the program after the
installation. If :variable:`CPACK_IFW_PACKAGE_RUN_PROGRAM` is set but no
- description provided, the UI will display ``Run <Name> now``. instead.
+ description is provided, QtIFW will use a default message like
+ ``Run <Name> now``.
- This feature is available for QtIFW 4.0.0 and newer.
+ This feature is available for QtIFW 4.0.0 and later.
.. variable:: CPACK_IFW_PACKAGE_SIGNING_IDENTITY
- .. versionadded: 3.23
+ .. versionadded:: 3.23
Allows specifying a code signing identity to be used for signing the generated
- app bundle. Only available on macOS.
+ app bundle. Only available on macOS, ignored on other platforms.
.. variable:: CPACK_IFW_ARCHIVE_FORMAT
@@ -317,27 +331,30 @@ Package
If the Qt Installer Framework tools were built without libarchive support,
only ``7z`` format is supported.
- This feature is available for QtIFW 4.2.0 and newer.
+ This feature is available for QtIFW 4.2.0 and later.
.. variable:: CPACK_IFW_ARCHIVE_COMPRESSION
.. versionadded:: 3.23
- Archive compression level. Defaults to 5 (*Normal compression*).
+ Archive compression level. The allowable values are:
* 0 (*No compression*)
- * 1 (*Fastest compressing*)
- * 3 (*Fast compressing*)
- * 5 (*Normal compressing*)
- * 7 (*Maximum compressing*)
- * 9 (*Ultra compressing*)
+ * 1 (*Fastest compression*)
+ * 3 (*Fast compression*)
+ * 5 (*Normal compression*)
+ * 7 (*Maximum compression*)
+ * 9 (*Ultra compression*)
+
+ If this variable is not set, QtIFW will use a default compression level,
+ which will typically be 5 (*Normal compression*).
.. note::
Some formats do not support all the possible values. For example ``zip``
compression only supports values from 1 to 7.
- This feature is available for QtIFW 4.2.0 and newer.
+ This feature is available for QtIFW 4.2.0 and later.
Components
""""""""""
@@ -348,16 +365,17 @@ Components
.. variable:: CPACK_IFW_PACKAGES_DIRECTORIES
- Additional prepared packages dirs that will be used to resolve
+ Additional prepared packages directories that will be used to resolve
dependent components.
.. variable:: CPACK_IFW_REPOSITORIES_DIRECTORIES
.. versionadded:: 3.10
- Additional prepared repository dirs that will be used to resolve and
- repack dependent components. This feature available only
- since QtIFW 3.1.
+ Additional prepared repository directories that will be used to resolve and
+ repack dependent components.
+
+ This feature is available for QtIFW 3.1 and later.
QtIFW Tools
"""""""""""
@@ -366,10 +384,11 @@ QtIFW Tools
.. versionadded:: 3.3
- The version of used QtIFW tools.
+ The version of the QtIFW tools that will be used. This variable is set
+ by the :module:`CPackIFW` module.
The following variables provide the locations of the QtIFW
-command-line tools as discovered by the module :module:`CPackIFW`.
+command-line tools as discovered by the :module:`CPackIFW` module.
These variables are cached, and may be configured if needed.
.. variable:: CPACK_IFW_ARCHIVEGEN_EXECUTABLE
@@ -397,30 +416,33 @@ These variables are cached, and may be configured if needed.
Hints for Finding QtIFW
"""""""""""""""""""""""
-Generally, the CPack ``IFW`` generator automatically finds QtIFW tools,
-but if you don't use a default path for installation of the QtIFW tools,
-the path may be specified in either a CMake or an environment variable:
+Generally, the CPack ``IFW`` generator automatically finds QtIFW tools.
+The following (in order of precedence) can also be set to augment the
+locations normally searched by :command:`find_program`:
.. variable:: CPACK_IFW_ROOT
- .. versionadded:: 3.9
+ .. versionadded:: 3.9
+
+ CMake variable
+
+.. envvar:: CPACK_IFW_ROOT
- An CMake variable which specifies the location of the QtIFW tool suite.
+ .. versionadded:: 3.9
- The variable will be cached in the ``CPackConfig.cmake`` file and used at
- CPack runtime.
+ Environment variable
.. variable:: QTIFWDIR
- An environment variable which specifies the location of the QtIFW tool
- suite.
+ CMake variable
-.. note::
- The specified path should not contain "bin" at the end
- (for example: "D:\\DevTools\\QtIFW2.0.5").
+.. envvar:: QTIFWDIR
+
+ Environment variable
-The :variable:`CPACK_IFW_ROOT` variable has a higher priority and overrides
-the value of the :variable:`QTIFWDIR` variable.
+.. note::
+ The specified path should not contain ``bin`` at the end
+ (for example: ``D:\\DevTools\\QtIFW2.0.5``).
Other Settings
^^^^^^^^^^^^^^
@@ -428,7 +450,7 @@ Other Settings
Online installer
""""""""""""""""
-By default, this generator generates an *offline installer*. This means that
+By default, this generator generates an *offline installer*. This means
that all packaged files are fully contained in the installer executable.
In contrast, an *online installer* will download some or all components from
@@ -458,14 +480,13 @@ CMake script. This is an optional feature.
Installers created by QtIFW tools have built-in support for
internationalization and many phrases are localized to many languages,
-but this does not apply to the description of the your components and groups
-that will be distributed.
+but this does not apply to the description of your components and groups.
Localization of the description of your components and groups is useful for
users of your installers.
-A localized variable or argument can contain a single default value, and a
-set of pairs the name of the locale and the localized value.
+A localized variable or argument can contain a single default value, and
+after that a set of pairs with the name of the locale and the localized value.
For example:
@@ -483,16 +504,16 @@ See Also
Qt Installer Framework Manual:
* Index page:
- http://doc.qt.io/qtinstallerframework/index.html
+ https://doc.qt.io/qtinstallerframework/index.html
* Component Scripting:
- http://doc.qt.io/qtinstallerframework/scripting.html
+ https://doc.qt.io/qtinstallerframework/scripting.html
* Predefined Variables:
- http://doc.qt.io/qtinstallerframework/scripting.html#predefined-variables
+ https://doc.qt.io/qtinstallerframework/scripting.html#predefined-variables
* Promoting Updates:
- http://doc.qt.io/qtinstallerframework/ifw-updates.html
+ https://doc.qt.io/qtinstallerframework/ifw-updates.html
Download Qt Installer Framework for your platform from Qt site:
- http://download.qt.io/official_releases/qt-installer-framework
+ https://download.qt.io/official_releases/qt-installer-framework