Configuration File

The configuration file customizes the UI and behavior of an installer. The file is typically called config.xml and located in the config directory.

A minimal configuration file consists of an <Installer> root element with <Name> and <Version> elements as children. All other elements are optional, and can appear in arbitrary order.

The following example shows a typical configuration file:

<?xml version="1.0"?>
<Installer>
    <Name>Some Application</Name>
    <Version>1.0.0</Version>
    <Title>Some Application Setup</Title>
    <Publisher>Your Company</Publisher>
    <ProductUrl>http://www.your-fantastic-company.com</ProductUrl>
    <InstallerWindowIcon>installericon</InstallerWindowIcon>
    <InstallerApplicationIcon>installericon</InstallerApplicationIcon>
    <Logo>logo.png</Logo>
    <Watermark>watermark.png</Watermark>
    <RunProgram>@TargetDir@/YourAppToRun</RunProgram>
    <RunProgramArguments>
        <Argument>Argument 1</Argument>
        <Argument>Argument 2</Argument>
    </RunProgramArguments>
    <RunProgramDescription>My nice application</RunProgramDescription>
    <StartMenuDir>Some Application Entry Dir</StartMenuDir>
    <MaintenanceToolName>SDKMaintenanceTool</MaintenanceToolName>
    <AllowNonAsciiCharacters>true</AllowNonAsciiCharacters>
    <Background>background.png</Background>

    <TargetDir>@HomeDir@/testinstall</TargetDir>
    <AdminTargetDir>@RootDir@/testinstall</AdminTargetDir>
    <RemoteRepositories>
        <Repository>
            <Url>http://www.your-repo-location/packages/</Url>
        </Repository>
    </RemoteRepositories>
    <AliasDefinitionsFile>aliases.xml</AliasDefinitionsFile>
</Installer>

Summary of Configuration File Elements

The following table summarizes the elements in the configuration file.

Note: We recommend that you place all files that you refer to in the configuration file in the config directory. However, you can also use relative paths, which the tools resolve relative to the location of the config.xml file.

Note: The filenames of the referred files must be unique. That is, if you want to use the same image for both <Logo> and <Watermark>, you must add two copies of the image file with different filenames.

You can use predefined variables (embedded in @ characters) as values of the elements. For more information, see Predefined Variables.

ElementDescription
Name Name of the product being installed. This is mandatory.
VersionVersion of the product being installed in the following format: [0-9]+((\.|-)[0-9]+)* such as 1-1; 1.2-2; 3.4.7. This is mandatory.
TitleName of the installer as displayed on the title bar.
PublisherPublisher of the software (as shown in the Windows Control Panel).
ProductUrlURL to a page that contains product information on your web site.
InstallerApplicationIconFilename for a custom installer icon. The actual file is looked up by attaching a '.icns' (macOS), '.ico' (Windows) suffix. No functionality on Unix.
InstallerWindowIconFilename for a custom window icon in PNG format for the Installer application. Used on Windows and Linux, no functionality on macOS.
LogoFilename for a logo in PNG format used as QWizard::LogoPixmap.
WatermarkFilename for a watermark in PNG format used as QWizard::WatermarkPixmap. If <WizardShowPageList> is set to true, the watermark is hidden.
BannerFilename for a banner in PNG format used as QWizard::BannerPixmap (only used by ModernStyle).
BackgroundFilename for an image in PNG format used as QWizard::BackgroundPixmap (only used by MacStyle). If <WizardShowPageList> is set to true, the background is hidden.
PageListPixmapFilename for an image in PNG format shown on top of installer page list. The image is shown only if <WizardShowPageList> is also set to true.
WizardStyleSet the wizard style to be used ("Modern", "Mac", "Aero" or "Classic").
StyleSheetSet the stylesheet file.
WizardDefaultWidthSets the default width of the wizard in pixels. Setting a banner image will override this. You can add the em or ex suffix to the specified value to use the em or ex unit, as in a CSS file.
WizardDefaultHeightSets the default height of the wizard in pixels. Setting a watermark image will override this. You can add the em or ex suffix to the specified value to use the em or ex unit, as in a CSS file.
WizardMinimumWidthSets the minimum width of the wizard in pixels. You can add the em or ex suffix to the specified value to use the em or ex unit, as in a CSS file.
WizardMinimumHeightSets the minimum height of the wizard in pixels. You can add the em or ex suffix to the specified value to use the em or ex unit, as in a CSS file.
WizardShowPageListSet to false if the widget listing installer pages on the left side of the wizard should not be shown. Defaults to true. If visible, this widget hides QWizard::WatermarkPixmap on QWizard::ClassicStyle and QWizard::ModernStyle, and QWizard::BackgroundPixmap on QWizard::MacStyle.
ProductImagesA list of images to be shown on PerformInstallationPage. This element can have one or several <ProductImage> child elements that contain an <Image> child element and an optional <Url> child element. The <Image> element specifies a filename for an image in PNG format. Optional <Url> can be specified for each image. Clicking on the image will open the <Url> in a browser. If the <Url> is a reference to a file, it will be opened with a suitable application instead of a Web browser.
TitleColorSet the color of the titles and subtitles (takes an HTML color code, such as "#88FF33").
RunProgramCommand executed after the installer is done if the user accepts the action. Provide the full path to the application.
RunProgramArgumentsArguments passed to the program specified in <RunProgram>. You can add several <Argument> child elements that each specify an argument to <RunProgram>.
RunProgramDescriptionText shown next to the check box for running the program after the installation. If <RunProgram> is set but no description provided, the UI will display Run <Name> now. instead.
StartMenuDirName of the default program group for the product in the Windows Start menu.
TargetDirDefault target directory for installation. On Linux, this is usually the user's home directory.
AdminTargetDirDefault target directory for installation with administrator rights. Only available on Linux, where you usually do not want to install in the administrator user's home directory.
LocalCacheDirDirectory name for storing the metadata cache. This does not include the leading directories, which are determined automatically based on a suitable platform specific location for storing cache files. The user may override the path from the installer settings. The default value is a UUID generated from the name of the product being installed.
PersistentLocalCacheSet to false if the fetched metadata should be removed from the local cache when the installer exits. Otherwise the contents of the cache are kept to speed up subsequent fetches. Defaults to true.
RemoteRepositoriesList of remote repositories. This element can contain several <Repository> child elements that each contain the <Url> child element that specifies the URL to access the repository. For more information, see Configuring Repositories.
RepositoryCategoriesName of a category that can contain a list of <RemoteRepositories> child elements. For more information, see Configuring Repository Categories.
MaintenanceToolNameFilename of the generated maintenance tool. Defaults to maintenancetool. The platform-specific executable file extension is appended.
MaintenanceToolIniFileFilename for the configuration of the generated maintenance tool. Defaults to MaintenanceToolName.ini.
MaintenanceToolAliasFilename for an alias of the maintenance tool that will be created to the Applications directory. Optional. Only used on macOS.
RemoveTargetDirSet to false if the target directory should not be deleted when uninstalling.
AllowNonAsciiCharactersSet to true if the installation path can contain non-ASCII characters.
DisableAuthorizationFallbackSet to true if the installation should not ask users to run the authorization fallback in case of authorization errors. Instead abort the installation immediately.
DisableCommandLineInterfaceSet to true if command line interface features should be disabled. This prevents the user from passing any consumer command to installer, like install, update and remove. Other options can still be used normally. Defaults to false.
RepositorySettingsPageVisibleSet to false to hide the repository settings page inside the settings dialog.
AllowRepositoriesForOfflineInstallerSet to false to disable usage of any temporary or user configured repositories set for offline installers. The maintenance tool written by an offline installer can still access the repositories. Defaults to true.
AllowSpaceInPathSet to false if the installation path cannot contain space characters.
DependsOnLocalInstallerBinarySet to true if you want to prohibit installation from an external resource, such as a network drive. This might make sense for e.g. very big installers. The option is only used on Windows.
TargetConfigurationFileFilename for the configuration file on the target. Default is components.xml.
AliasDefinitionsFileFilename for a XML document containing the definitions for component aliases. For more information about how to declare component aliases in the file, see Alias Definition File.
TranslationsList of translation files to be used for translating the user interface. To add several translation files, specify several <Translation> child elements that each specify the name of the translation. Optional. For more information, see Translating Pages and Configuring and Overwriting Default Translations.
UrlQueryStringThis string needs to be in the form "key=value" and will be appended to archive download requests. This can be used to transmit information to the webserver hosting the repository.
ControlScriptFilename for a custom installer control script. See Controller Scripting.
CreateLocalRepositorySet to true if you want to create a local repository inside the installation directory. This option has no effect on online installers. The repository will be automatically added to the list of default repositories.
InstallActionColumnVisibleSet to true if you want to add an extra column into component tree showing install actions. This extra column indicates whether a component is going to be installed or uninstalled, or just stay installed or uninstalled.
SupportsModifySet to false if the product does not support modifying an existing installation.
SaveDefaultRepositoriesSet to false if default repositories <RemoteRepositories> should not be saved to MaintenanceToolName.ini. By default default repositories are saved. Not saving the repositories means than when you run maintenancetool there are no default repositories in use.
AllowUnstableComponentsSet to true if other components are allowed to be installed although there are unstable components. A component is unstable if it is missing a dependency, has errors in scripts, and so on. Unstable components are grayed in the component tree, and therefore cannot be selected. By default, the value is false which means that the installation will be aborted if unstable components are found.

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