Tools
The Qt Installer Framework contains the following tools:
installerbase
The installerbase tool describes the core installer itself. All data and meta information will be packed to this binary. For the installer creation process you will not need to call it directly.
binarycreator
Use the binarycreator tool to create offline and online installers. Component information and data are appended to the offline installer binary, which enables the file extraction and post installation scripts to work without an Internet connection.
Online installers store the location of the repository that contains the data. On startup, they load the component information, not the data.
You can also create hybrid installers that store some components locally and receive others via a network connection. For more information, see Reducing Installer Size.
For information about how to implement data integration into the installer binary, see QInstaller::BinaryContent.
Note: If you change this configuration, you must recompile the installerbase tool.
Using binarycreator
You can use the binarycreator tool to create offline and online installers. Some options have default values, and therefore, you can omit them.
To create an offline installer (in Windows), enter the following command:
- On Windows:
<location-of-ifw>\binarycreator.exe -t <location-of-ifw>\installerbase.exe -p <package_directory> -c <config_directory>\<config_file> <installer_name>
- On Linux and macOS
<location-of-ifw>/binarycreator -t <location-of-ifw>/installerbase -p <package_directory> -c <config_directory>/<config_file> <installer_name>
To create an online only installer, you can use the –online-only which defines all packages to install from an online repository on a web server:
- On Windows:
<location-of-ifw>\binarycreator.exe -t <location-of-ifw>\installerbase.exe -p <package_directory> -c <config_directory>\<config_file> -e <packages> <installer_name>
- On Linux and macOS
<location-of-ifw>/binarycreator -t <location-of-ifw>/installerbase -p <package_directory> -c <config_directory>/<config_file> -e <packages> <installer_name>
Summary of binarycreator Parameters
The binarycreator tool accepts the following parameters:
| Parameter | Use |
|---|---|
| -t or –template file | Use file as an installer template binary to which the component information is appended. If you omit this parameter, the installerbase template is used. |
| -p or –packages directory | Use directory as the package directory. Defaults to the current working directory. |
| –repository directory | Use directory as the repository directory with packages to repack. This entry can be given multiple times. |
| -n or –online-only | Compile without any component in the installer binary. |
| -f or –offline-only | Create an offline installer that never accesses online repositories. |
| -c or –config file | Use file as the config file. |
| -e or –exclude p1,...,pn | Comma-separated list of packages to retrieve from an online repository. The packages are not included in the installer binary. |
| -i or –include p1,...,pn | Comma-separated list of packages to retrieve from the installer binary. You cannot combine or merge --include and --exclude. |
| -r or –resources | Comma-separated list of resources to include in the installer binary. |
| –ignore-translations | Disable the use of translation files to make testing faster. |
| –ignore-invalid-packages | Ignore component or package directories that do not have valid metadata information (package.xml) to make testing faster. |
| –ignore-invalid-repositories | Ignore repository directories that do not have valid metadata information (Updates.xml) instead of aborting. |
| -v or –verbose | Display debug output. |
| -s or –sign identity | Only available on macOS. Allows specifying a code signing identity to be used for signing the generated app bundle. |
| –af or –archive-format 7z|zip|tar|tar.gz|tar.bz2|tar.xz | Set the format used when packaging new component data archives. If you omit this option, the 7z format will be used as a default. Note: If the Installer Framework tools were built without libarchive support, only |
| –ac or –compression <5> | Defaults to 5 (Normal compression). Note: Some formats do not support all the possible values, for example bzip2 compression only supports values from 1 to 9.
|
These parameters are followed by the name of the target binary and a list of packages to be available for installation.
Note: The listed packages are included in the installer, as well as all their dependencies and all packages that share the same prefix, unless you specify the --nodeps parameter.
In the optional resource files specified via the --resources parameter, a special fonts/ path can be used to ship custom fonts. These fonts will be loaded automatically and thus become available in a stylesheet which can be specified via the StyleSheet variable.
On Windows, the name of the target binary is automatically extended with .exe, if you do not specify the extension. On Mac, the target is created as an application bundle with the extension .app, which is automatically added, if not supplied. Additionally, you can specify the .dmg extension, which creates a DMG disk image that contains an .app bundle.
Using Icons
On macOS, if the target binary is suffixed with .app, a macOS application bundle is created. The icon that you specify in config.xml is extended with .icns and used as the icon for the created bundle.
On Windows, the icon that you specify in config.xml is extended with .ico and used as the application icon for the .exe file.
On Linux, the icon that you specify in config.xml is extended with .png and used as the window icon.
repogen
Use the repogen tool to generate online repositories.
The repogen tool expects the following parameters in the following order:
repogen.exe -p <package_directory> <repository_directory>
When the repository has been created, you can upload it anywhere. You must specify the location in the installer configuration file when creating an installer for it.
Repositories contain compressed metadata that can be packaged as a separate 7z archive for each component, or combined into a single 7z archive for the repository entirety. By default, repogen packages the metadata in both formats for backward compatibility with older installers not supporting the unified meta-format. This can be changed with the --unite-metadata and --component-metadata options.
You can use an existing repository to repack packages to another repository or offline installer.
Summary of repogen Parameters
| Parameter | Use |
|---|---|
| -p or –packages directory | Use directory as the package directory. This is mandatory. |
| –repository directory | Use directory as the repository directory with packages to repack (not to confuse with the mandatory target repository directory). This entry can be given multiple times. |
| repository directory | Target directory for the repository. During an initial installation, the directory must not yet exist. When updating, the directory may exist and its contents may be overwritten or removed. This is mandatory. |
| -e or –exclude p1,...,pn | Comma-separated list of packages to be ignored from the set of all packages in the packages directory. |
| -i or –include p1,...,pn | Comma-separated list of packages to be used from the set of all packages in the packages directory. |
| –update | Update all packages in the packages directory. The list can be further filtered with the -i, -e parameters. |
| –update-new-components | Update only components that are new or have a newer version. The list can be further filtered with the -i, -e parameters. |
| -r or –remove | Force removal of existing target directory before generating it again. |
| -v or –verbose | Display debug output. |
| –unite-metadata | Combine all metadata into one 7z. This speeds up metadata download phase. |
| –component-metadata | Creates one metadata 7z per component. |
| -s or –sha-update p1,...,pn | Comma-separated list of packages to be updated based on the component sha checksum instead of the version number. This parameter adds a new <ContentSha1> node to the Updates.xml. |
| –af or –archive-format 7z|zip|tar|tar.gz|tar.bz2|tar.xz | Set the format used when packaging new component data archives. If you omit this option, the 7z format will be used as a default. Note: If the Installer Framework tools were built without libarchive support, only |
| –ac, –compression <5> | Defaults to 5 (Normal compression). Note: Some formats do not support all the possible values, for example bzip2 compression only supports values from 1 to 9.
|
Note: We recommend that you use the --update-new-packages parameter to update an existing repository, especially if you have a content delivery system. This helps you avoid updating components that have not changed and this makes it much easier for a content delivery system to distribute only new files, because only the updated components are assigned new SHA checksums.
archivegen
You can use archivegen to package files and directories into archives.
The archivegen tool expects the following parameters in the following order:
archivegen <archive_name> <data>
Where <archive_name> is the path and file name of the archive to create and <data> contains the paths and names of the files or directories to package into the archive, separated by spaces.
Summary of archivegen Parameters
| Parameter | Use |
|---|---|
| -h, –help | Displays this help. |
| -v, –version | Displays version information. |
| -f, –format <format> | Format for the archive. Defaults to 7z. Note: If the Installer Framework tools were built without libarchive support, only
|
| -c, –compression <5> | Defaults to 5 (Normal compression). Note: Some formats do not support all the possible values, for example bzip2 compression only supports values from 1 to 9.
|
devtool
You can use devtool to update an existing installer or maintenance tool with a new installer base, to dump binary content from an installer or maintenance tool to a target, and to execute operations. For a summary of available operations, see Operations.
devtool expects the following parameters in the following order:
devtool [options] binary
Where binary is the path and name of an existing installer or maintenance tool.
Summary of devtool Parameters
| Parameter | Use |
|---|---|
| -?, -h, –help | Display help. |
| -v, –version | Display version information. |
| –verbose | Display additional information. |
| update <binary> <installerbase> | Update an existing installer or maintenance tool with a new installer base. |
| dump <binary> <folder> | Dump the binary content that belongs to an installer or maintenance tool into the target. |
| operation <mode,name,args,...> | Execute an operation with a list of arguments.
|
© 2021 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. The Qt Company, Qt and their respective logos are trademarks of The Qt Company Ltd in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
