/**************************************************************************** ** ** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the Qt Installer Framework. ** ** $QT_BEGIN_LICENSE:FDL$ ** Commercial License Usage ** Licensees holding valid commercial Qt licenses may use this file in ** accordance with the commercial license agreement provided with the ** Software or, alternatively, in accordance with the terms contained in ** a written agreement between you and Digia. For licensing terms and ** conditions see http://qt.digia.com/licensing. For further information ** use the contact form at http://qt.digia.com/contact-us. ** ** GNU Free Documentation License Usage ** Alternatively, this file may be used under the terms of the GNU Free ** Documentation License version 1.3 as published by the Free Software ** Foundation and appearing in the file included in the packaging of ** this file. Please review the following information to ensure ** the GNU Free Documentation License version 1.3 requirements ** will be met: http://www.gnu.org/copyleft/fdl.html. ** $QT_END_LICENSE$ ** ****************************************************************************/ // ********************************************************************** // NOTE: the sections are not ordered by their logical order to avoid // reshuffling the file each time the index order changes (i.e., often). // Run the fixnavi.pl script to adjust the links to the index order. // ********************************************************************** /*! \contentspage{index.html}{Qt Installer Framework} \page index.html \nextpage ifw-overview.html \title Qt Installer Framework Manual \section1 Version \ifwversion The Qt Installer Framework provides a set of tools and utilities to create installers for the supported desktop Qt platforms: Linux, Microsoft Windows, and Mac OS X. \note Report bugs and suggestions for the Qt Installer Framework project in the \l{https://bugreports.qt-project.org/browse/QTIFW}{Qt Bugtracker}. \list \o \l{Overview of Qt Installer Framework} \o \l{Getting Started} \o \l{End User Workflows} \list \o \l{Initial Installation} \o \l{Adding Components} \o \l{Removing Components} \o \l{Updating Components} \o \l{Specifying Settings} \endlist \o \l{Tutorial: Creating an Installer} \o \l{Creating Installers} \list \o \l{Creating Offline Installers} \o \l{Creating Online Installers} \o \l{Promoting Updates} \o \l{Customizing Installers} \endlist \o \l{Reference} \list \o \l{Configuration File} \o \l{Package Directory} \o \l{Installer Pages} \o \l{Component Scripting} \o \l{Operations} \o \l{Tools} \endlist \o \l{Known Issues} \endlist */ /*! \contentspage index.html \previouspage ifw-tutorial.html \page ifw-creating-installers.html \nextpage ifw-offline-installers.html \title Creating Installers The following steps are needed to create offline and online installers: \list 1 \o Create a \e {package directory} for the installable components. For more information, see \l{Package Directory}. \o Create a configuration file called \c config.xml in the \c config directory. It contains information about how to build the installer binaries and online repositories. For more information about the file format and available settings, see \l{Configuration File}. \o Create a package information file called \c package.xml in the \c {config\meta} directory. It contains settings for deployment and the installation process. For more information, see \l{Meta Directory}. \o Create installer content and copy it to the package directory. For more information, see \l{Data Directory}. \o For online installers, use the \c repogen tool to create the repository that contains the installable content and upload the repository to a web server. \o Use the \c binarycreator tool to create the installer. For more information, see \l{Tools}. \endlist For an example of how to create a simple installer that uses the predefined installer pages, see \l{Tutorial: Creating an Installer}. The following sections describe how to create different types of installers: \list \o \l{Creating Offline Installers} \o \l{Creating Online Installers} \o \l{Promoting Updates} \o \l{Customizing Installers} \endlist */ /*! \contentspage index.html \previouspage ifw-reference.html \page ifw-globalconfig.html \nextpage ifw-component-description.html \title Configuration File The configuration file customizes the UI and behavior of an installer. The file is typically called \c config.xml and located in the \c config directory. A minimal configuration file consists of an \c root element with \c and \c elements as children. All other elements are optional, and can appear in arbitrary order. The following example shows a typical configuration file: \quotefile examples/config.xml \section1 Supported Configuration Settings The following table summarizes the settings in the configuration file. \note We recommend that you place all files that you refer to in the configuration file in the \c config directory. However, you can also use relative paths, which the tools resolve relative to the location of the config.xml file. \table \header \o Setting \o Description \row \o Name \o Name of the product being installed. This is mandatory. \row \o Version \o Version number of the product being installed. This is mandatory. \row \o Title \o Name of the installer as displayed on the title bar. \row \o Publisher \o Publisher of the software (as shown in the Windows Control Panel). \row \o ProductUrl \o URL to a page that contains product information on your web site. \row \o Icon \o Filename for a custom installer icon. The actual file is looked up by attaching a '.icns' (Mac OS X), '.ico' (Windows) or '.png' (Unix) suffix. \row \o Logo \o Filename for a logo used as \a QWizard::LogoPixmap. \row \o LogoSmall \o Filename for a logo used as \a QWizard::LogoSmallPixmap. \row \o Watermark \o Filename for a watermark used as \a QWizard::WatermarkPixmap. \row \o Background \o Filename for an image used as \a QWizard::BackgroundPixmap. \row \o RunProgram \o Command executed after the installer is done if the user accepts the action. \row \o RunProgramDescription \o Text shown next to the check box for running the program after the installation. Defaults to \gui {Run }. \row \o StartMenuDir \o Name of the default program group for the product in the Windows \gui Start menu. \row \o TargetDir \o Default target directory for installation. \row \o AdminTargetDir \o Default target directory for installation with administrator rights. \row \o RemoteRepositories \o List of remote repositories. You can add several \c Repository sections that each specify the \c Url to access the repository. For more information, see \l{Configuring Repositories}. \row \o UninstallerName \o Filename of the generated uninstaller. Defaults to \e uninstall. The platform-specific executable file extension is appended. \row \o UninstallerIniFile \o Filename for the configuration of the generated uninstaller. Defaults to \e {UninstallerName}.ini. \row \o RemoveTargetDir \o Set to \c false if the target directory should not be deleted when uninstalling. \row \o AllowNonAsciiCharacters \o Set to \c true if the installation path can contain non-ASCII characters. \row \o RepositorySettingsPageVisible \o Set to \c false to hide the repository settings page inside the settings dialog. \row \o AllowSpaceInPath \o Set to \c true if the installation path can contain space characters. \row \o DependsOnLocalInstallerBinary \o Set to \c 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. \row \o TargetConfigurationFile \o Filename for the configuration file on the target. Default is components.xml. \row \o Pages \o Custom strings for labels in the installer pages. Deprecated, see \l{Translating Pages} instead. \endtable */ /*! \contentspage index.html \previouspage ifw-updates.html \page ifw-customizing-installers.html \nextpage ifw-reference.html \title Customizing Installers The following sections describe how you can extend the predefined installer by adding operations to the pages and by adding new pages and language variants. \section1 Adding Operations Components can use the ECMAScript scripting language to perform additional operations at any time during the installation process. Typically, components manipulate files by moving, copying, or patching them. For more information about scripting, see \l{Component Scripting}. \section1 Adding Pages A component can contain one or more user interface files, which are placed into the installer by a script. The installer automatically loads all user interface files listed in package.xml. You can access the loaded widgets by calling \a QInstaller::Component::userInterface with the class name of the widget, as illustrated by the following code snippet: \code component.userInterface( "MyPage" ).checkbox.checked = true; \endcode To add a new page to the installer, use the \a QInstaller::Installer::addWizardPage method and specify the location of the new page. For example, the following code adds an instance of \a MyPage before the ready for installation page: \code installer.addWizardPage( component, "MyPage", QInstaller.ReadyForInstallation ); \endcode \section1 Adding Widgets You can also insert custom user interface elements into the installer as single widgets (such as a check box). To insert a single widget, use the \a QInstaller::Installer::addWizardPageItem method. For example, the following code snippet adds an instance of \a MyWidget to the component selection page from within a script: \code installer.addWizardPageItem( component, "MyWidget", QInstaller.ComponentSelection ); \endcode \section1 Translating Pages The installer uses the Qt Translation system to support the translation of user-readable output to several languages. To provide end users with localized versions of strings contained in the component scripts and user interfaces, create QTranslator files that the installation system loads along with the the component. The installer loads the translation file that matches the current system locale. For example, if the system locale is German, the de_de.qm file is loaded. Use the \a {qsTr()} function for literal text within scripts. Additionally, you can add the \a Component.prototype.retranslateUi method to the script. It is called when the language of the installer changes and the translation file is loaded. The context being used for translation is the basename of the script file when using \a qsTr or the class name of the UI file when translating a user interface. \note The translation system can also be used to customize the UI. Use e.g. an \c en_en.ts file to replace any text in the installer with a custom English version. */ /*! \contentspage index.html \previouspage ifw-globalconfig.html \page ifw-component-description.html \nextpage noninteractive.html \title Package Directory Installers contain components that are either embedded to the installer or loaded from a remote repository. In both cases, you need to use a file format and structure for the components that the installer can read. \section1 Package Directory Structure Place all components in the same root directory, which is called the \e {package directory}. The directory name acts as a domain-like identifier, which identifies all components. For example, \c com.vendor.root. Within the root directory, create subdirectories called \c data and \c meta. A package directory can look as follows: \code -packages - com.vendor.root - data - meta - com.vendor.root.component1 - data - meta - com.vendor.root.component1.subcomponent1 - data - meta - com.vendor.root.component2 - data - meta \endcode \section1 Meta Directory The \c meta directory contains files that specify settings for deployment and the installation process. The files are not extracted by the installer. The directory must contain at least a package information file and all files that you refer to in the package information file, such as scripts, user interface files, and translations. \section2 Package Information File Syntax The package.xml file is the main source of information about a component. The following is an example of a package file: \quotefile examples/package.xml \section2 Summary of Package Information File Settings \table \header \o Setting \o Description \row \o DisplayName \o Human-readable name of the component. Required. \row \o Description \o Human-readable description of the component. Required. Specify translations for the description as values of additional Description tags, with the xml:lang attribute set to the correct locale. If a localization that matches the locale is not found and an untranslated version exists, that one will be used. Otherwise no Description will be shown for that locale. \row \o Version \o Version number of the component in the following format: [0-9]+((\.|-)[0-9]+)* such as 1-1; 1.2-2; 3.4.7. Required. If a package needs to show the version number from a child rather than it's own (due to grouping of child packages) one can specify the attribute inheritVersionFrom with the package name the version needs to be inherited from. \row \o ReleaseDate \o Date when this component version was released. Required. \row \o Name \o Domain-like identification for this component. Required. \row \o Dependencies \o Comma-separated list of identifiers of components that this component depends on. Optionally, you can specify version numbers, separated by a dash (-). You can prefix version numbers with a comparison operator (=, >, <, >= or <=). Optional. For more information, see \l{Component Dependencies}. \row \o AutoDependOn \o Opposite of dependencies. Defines that this component should be loaded if the specified component is loaded. \row \o Virtual \o Set to \c true to hide the component from the installer. \row \o SortingPriority \o Priority of the component in the tree. The tree is sorted from highest to lowest priority, with the highest priority on the top. \row \o Licenses \o List of license agreements to be accepted by the installing user. To add several licenses, specify several \c License sections that each specify the license \c name and \c file. If there are translations listed for this component, the installer will also look for translated licenses. These need to have the same name as the original license file but with an added locale identifier. If for example the license file is called license.txt and there is German translation specified, the installer will also include a license_de_de.txt file (and show that when installing on a German system). \row \o Script \o File name of a script being loaded. Optional. For more information, see \l{Adding Operations}. \row \o UserInterfaces \o List of pages to load. To add several pages, specify several \c UserInterface sections that each specify the filename of a page. Optional. For more information, see \l{Adding Pages}. \row \o Translations \o List of translation files to load. To add several language variants, specify several \c Translation sections that each specify the filename of a language variant. Optional. For more information, see \l{Translating Pages}. \row \o UpdateText \o Description added to the component description if this is an update to the component. Optional. \row \o Default \o Possible values are: \c true, \c false, and \c script. Set to \c true to preselect the component in the installer. The boolean values are evaluated directly, while \c script is resolved during runtime. Add the name of the script as a value of the \c Script setting in this file. For an example script, see \l{Selecting Default Contents}. \row \o Essential \o Marks the package as essential to force a restart of the \c UpdateAgent or \c MaintenanceTool. This is relevant for updates found with \c UpdateAgent. \row \o ForcedInstallation \o Determines that the package must always be installed. End users cannot deselect it in the installer. \row \o Replaces \o Comma-separated list of components to replace. Optional. \row \o DownloadableArchives \o Lists the data files (separated by commas) for an online installer to download. Optional. \endtable \section2 Component Dependencies Components can depend on one or several real or virtual components. Dependencies are defined by using the component identifier and, optionally, component version. Use a dash (-) to separate version numbers from identifiers. You can prefix version numbers with a comparison operator (=, >, <, >= or <=) to indicate that the version number of the package is compared to the required version and has to be equal to, greater than, less than, greater than or equal to, or less than or equal to the version number specified in the dependency. If no comparison operator is given, it defaults to =. \section1 Data Directory The \c data directory contains the content that is extracted during the installation. The Qt Installer Framework uses the archivegen tool to extract the files from a 7zip archive (.7z). You have the following options: \list \o Copy the files to the \c data directory. Before the installer is created, the files are packaged into a 7zip archive. \o Use the archivegen tool to package the files as a 7zip archive and copy it to the \c data directory. \o Use some other tool to package the files as a 7zip compatible archive and copy it to the \c data directory. \endlist \note Each of the above options has advantages and disadvantages. We recommend that you use archivegen because it offers faster archive creation and compatibility with 7zip. */ /*! \contentspage index.html \previouspage operations.html \page ifw-tools.html \nextpage ifw-knownissues.html \title Tools The Qt Installer Framework contains the following tools: \list \o \c installerbase \o \c binarycreator \o \c repogen \endlist \section1 installerbase The \c 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. \section1 binarycreator Use the \c 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 ###TODO insert link here. For information about how to implement data integration into the installer binary, see \a QInstaller::BinaryContent ###TODO insert link here. \note If you change this configuration, you must recompile the \c installerbase tool. \section2 Using binarycreator You can use the \c 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: \list \o On Windows: \code \binarycreator.exe -t \installerbase.exe -p -c \ \endcode \o On Linux and Mac OS X \code /binarycreator -t /installerbase -p -c / \endcode \endlist 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: \list \o On Windows: \code \binarycreator.exe -t \installerbase.exe -p -c \ -e \endcode \o On Linux and Mac OS X \code /binarycreator -t /installerbase -p -c / -e \endcode \endlist \section2 Summary of binarycreator Parameters The \c binarycreator tool accepts the following parameters: \table \header \o Parameter \o Use \row \o -t or --template file \o Use \c file as an installer template binary to which the component information is appended. If you omit this parameter, the \c installerbase template is used. \row \o -p or --packages directory \o Use \c directory as the \l{Package Directory Structure} {package directory}. Defaults to the current working directory. \row \o -n or --online-only \o Compile without any component in the installer binary. \row \o -f or --offline-only \o Create an offline installer that never accesses online repositories. \row \o -c or --config file \o Use \c file as the \l{Configuration File} {config file}. \row \o -e or --exclude p1,...,pn \o Comma-separated list of packages to retrieve from an online repository. The packages are not included in the installer binary. \row \o -i or --include p1,...,pn \o Comma-separated list of packages to retrieve from the installer binary. You cannot combine or merge \c {--include} and \c {--exclude}. \row \o -r or --resources \o Comma-separated list of resources to include in the installer binary. \row \o --ignore-translations \o Disable the use of translation files to make testing faster. \row \o --ignore-invalid-packages \o Ignore component or package directories that do not have valid metadata information (package.xml) to make testing faster. \row \o -v or --verbose \o Display debug output. \endtable 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 \c --nodeps parameter. 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. \section2 Using Icons On Mac OS X, if the target binary is suffixed with .app, a Mac OS X 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. \section1 repogen Use the \c repogen tool to generate online repositories. The \c repogen tool expects the following parameters in the following order: \code repogen.exe -p -c repository \endcode 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. \section2 Summary of repogen Parameters \table \header \o Parameter \o Use \row \o -p or --packages directory \o Use \c directory as the \l{Package Directory Structure} {package directory}. Defaults to the current working directory. \row \o -c or --config file \o Use \c file as the \l{Configuration File} {config file}. \row \o repository directory \o Target directory to generate the repository. Must not yet exist. \row \o components \o List of components to place into the repository. Includes dependencies. \row \o -e or --exclude p1,...,pn \o Comma-separated list of packages to be retrieved from an online repository. The packages are not included in the installer binary. \row \o -u updateurl \o Receive updates from another repository. \row \o --update \o Place only the specified packages in the repository, without their dependencies. Make sure to also add the Updates.xml from the repository to update. This option adds the files that you list in the \c {--include} parameter to the end of the Updates.xml file. \row \o -v or --verbose \o Display debug output. \endtable \note We recommend that you use the \c {--update} parameter to update an existing repository, especially if you have a content delivery system. In combination with the \c {--include} parameter which gets only the components with incremented version numbers it generates an update which contains only new files. 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. */ /*! \contentspage index.html \previouspage ifw-offline-installers.html \page ifw-online-installers.html \nextpage ifw-updates.html \title Creating Online Installers Online installers fetch the repository description (Updates.xml), in addition to the one stored inside of the binary. Create a repository and upload it to a web server. Then specify the location of the repository in the config.xml file that you use to create the installer. \section1 Creating Repositories Use the \c repogen tool to create online repositories of all packages of one package directory: repogen.exe -p -c \ repository For example, to create a repository that contains only com.nokia.sdk.qt and com.nokia.sdk.qtcreator, enter the following command: \code repogen.exe -p packages -c installer-config\config.xml -i com.nokia.sdk.qt,com.nokia.sdk.qtcreator repository \endcode When the repository has been created, upload it to a web server. You must specify the location of the repository in the installer configuration file. \section1 Configuring Repositories The \c RemoteRepositories setting in the installer configuration file (config.xml) can contain a list of several repositories. Each of them can have the following settings: \list \o URL, which points to a list of available components. \endlist The URL needs to point to the Updates.xml file that lists the available components. For example: \code http://www.yourcompany.com/packages 1 user password \endcode The installer works only if it can access the repository. If the repository is accessed after the installation, the maintenance tool rejects installation. However, uninstallation is still possible. A repository can be enabled or disabled by default. For repositories requiring authentication, the details can also be set here, although entering a password here is usually not advisable as it is saved in plain text. Authentication details not set here will be gotten at runtime using a dialog. The user can work around these settings at runtime. \section1 Creating Installer Binaries To create an online installer by using the \c binarycreator tool, enter the following command: \code \binarycreator.exe -t \installerbase.exe -p -c \ -e \endcode For example, enter the following command to create an installer binary called SDKInstaller.exe that will not contain data for com.nokia.sdk.qt and com.nokia.qtcreator, because those packages are downloaded from a remote repository: \code binarycreator.exe -p installer-packages -c installer-config\config.xml -e com.nokia.sdk.qt,com.nokia.qtcreator SDKInstaller.exe \endcode \section1 Reducing Installer Size Even if the components are fetched from a web server, \c binarycreator adds them to the installer binary by default. However, when the installer checks the web server for updates, end users are spared a download if new versions are not available. Alternatively, you can create online installers that do not contain any data and that fetch all the data from the web server. Use the \a{-n} parameter of the \c binarycreator tool and only add the root component to the installer. Usually the root component is empty and hence only adds the XML description of the root. For more information about the options that you have, see \l{Summary of binarycreator Parameters}. */ /*! \contentspage index.html \previouspage ifw-creating-installers.html \page ifw-offline-installers.html \nextpage ifw-online-installers.html \title Creating Offline Installers Offline installers do not try to connect to an online repository at all during installation. However, the metadata configuration (config.xml) enables users to add and update components online. Offline installers are especially useful in cases where a corporate firewall does not allow end users to connect to web servers. The network administrator can set up a local update service within the network. To create offline installers, use the \a{--offline-only} option of the \c binarycreator tool. To create an offline installer in Windows, enter the following command: \code \binarycreator.exe --offline-only -t \installerbase.exe -p -c \ \endcode Some options have default values, and therefore, you can omit them. For example, enter the following command to create an installer binary called SDKInstaller.exe that contains the packages identified by com.nokia.sdk and their dependencies: \code binarycreator.exe --offline-only -c installer-config -p installer-packes SDKInstaller.exe \endcode */ /*! \contentspage index.html \previouspage ifw-online-installers.html \page ifw-updates.html \nextpage ifw-customizing-installers.html \title Promoting Updates Create online installers to be able to promote updates to end users who install your product. The following steps are needed to promote updates: \list 1 \o Copy the updated content to the package directory. \o Increase the value of the \a{Version} setting for the updated components in the config.xml file. \o Use the \c repogen tool to recreate the online repository with the updated contents and to generate the update.xml file in the root directory of the repository. \o Upload the repository to the web server. \o Use the \c binarycreator tool to create the installer. \endlist \section1 Configuring Updates The installer downloads the Update.xml file on startup and compares the installed version with the version in the file. If the online version number in the file is greater than the local one, the installer displays it in the list of available updates. Increase the value of the \a{Version} setting for the component in the config.xml file. \section1 Recreating Repositories The easiest way to provide an update is to recreate the repository and upload it to the web server. For more information, see \l{Creating Repositories}. \section1 Partially Updating Repositories A full update of the whole repository might not be optimal if: \list \o The repository is very large, as uploading would take a long time. \o You want to deliver only the changed components. \endlist \note repogen recreates the 7zip archives each time it is being called. As 7zip stores the timestamps of the included files (which are moved or copied during this process), the SHA sum of each archive changes. SHA sums are used to verify the download of the archive and hence the SHA needs to match the 7zip. As the SHAs are stored in the Updates.xml file you will be forced to upload the full repository. This can be circumvented by using the \a{--update} option of repogen. \section2 Creating Partial Updates When recreating the online repository, use the \a{--update} parameter. It takes an existing repository as input and only changes the components that are specified as additional parameters. Only those SHA sums are changed in the global configuration as well. \section2 Uploading Partial Updates Upload the following items to the web server: \list \o The component directory (usually something like \a{com.vendor.product.updatedpart}). \o The global \a{Updates.xml} stored in the root directory of the online repository. \endlist \note The order of uploading items is very important. If you update the repository on a live server, first update the component and then Updates.xml. The package names include version numbers, and therefore, end users receive old packages until the new ones are fully uploaded. */ /*! \contentspage index.html \previouspage ifw-tools.html \page ifw-knownissues.html \title Known Issues Check the \l{https://bugreports.qt-project.org/browse/QTIFW}{Qt Bugtracker} for known issues in the Qt Installer Framework project. If you cannot find the issue there, create a bug report. */