Tools | Qt Installer Framework Manual

- Qt Installer Framework Manual
- Tools

Operations ◦ Scripting API

# Tools

The Qt Installer Framework contains the following tools:

- installerbase
- binarycreator
- repogen
- archivegen
- devtool

## 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 `7z` format is supported.

–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.

- 0 (No compression)
- 1 (Fastest compressing)
- 3 (Fast compressing)
- 5 (Normal compressing)
- 7 (Maximum compressing)
- 9 (Ultra compressing)

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 `7z` format is supported.

–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.

- 0 (No compression)
- 1 (Fastest compressing)
- 3 (Fast compressing)
- 5 (Normal compressing)
- 7 (Maximum compressing)
- 9 (Ultra compressing)

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 `7z` format is supported.

- 7z (7z archive)
- zip (ZIP archive)
- tar (uncompressed tar archive)
- tar.gz (gzip compressed tar archive)
- tar.bz2 (bzip2 compressed tar archive)
- tar.xz (xz compressed tar archive)

-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.

- 0 (No compression)
- 1 (Fastest compressing)
- 3 (Fast compressing)
- 5 (Normal compressing)
- 7 (Maximum compressing)
- 9 (Ultra compressing)

## 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. `mode` can be `DO` or `UNDO`, depending on whether the step contains instructions for the installer or uninstaller.

Operations ◦ Scripting API