/****************************************************************************
**
** This file is part of Qt Installer Framework
**
** Copyright (c) 2012 Nokia Corporation and/or its subsidiary(-ies).
**
** Contact: Nokia Corporation (qt-info@nokia.com)
**
**
** GNU Free Documentation License
**
** 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.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
**
****************************************************************************/
// **********************************************************************
// 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 1.2.1
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{Using Qt Installers}
\list
\o \l{Initial Installation}
\o \l{Adding Components}
\o \l{Removing Components}
\o \l{Updating Components}
\o \l{Specifying Settings}
\endlist
\o \l{Getting Started}
\o \l{Tutorial: Creating an Installer}
\o \l{Creating Qt 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 Qt 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
A configuration file called \c config.xml specifies how to build the
installer binaries and online repositories. The file is located in the
\c config directory.
\section1 Configuration File Syntax
The configuration file has the following syntax:
\code
Some Application
1.0.0
Some Application Setup
Your Company
http://www.your-fantastic-company.com
logo.png
watermark.png
Some Application Entry Dir
true
installericon
@homeDir@/testinstall
http://www.your-repo-location/packages/
\endcode
\section2 Summary of 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.
\row
\o Version
\o Version number of the product being installed.
\row
\o Title
\o Name of the installer as displayed on the title bar.
\row
\o Publisher
\o Publisher of the software.
\row
\o ProductUrl
\o URL to a page that contains product information on your web
site.
\row
\o Logo
\o Filename for a logo used as \a QWizard::LogoPixmap.
\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 Icon
\o Filename of the installer icon. On Windows, .ico is appended,
on Mac, .icns is appended, and on Linux, .png is appended.
\row
\o TargetDir
\o Default target directory for installation.
\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.
Optionally, you can add a \c Required section to specify whether
the installer should go ahead even if it cannot access the
server. Acceptable values are \c true and \c false. 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 AllowNonAsciiCharacters
\o Set to \c true if the installation path can contain non-ASCII
characters.
\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.
*/
/*!
\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:
\code
QtGui
Qt gui libraries
1.2.3
2009-04-23
com.vendor.root.component2
com.vendor.root.component1
false
specialpage.ui
errorpage.ui
sv_se.qm
de_de.qm
\endcode
\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.
\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.
\row
\o ReleaseDate
\o Date when this component version was released. Optional.
\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
lowest to highest priority, with the lowest 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 originial 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.
\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 installer, add the -e parameter which defines the
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 --nodeps
\o Compile only the selected packages. Do not compile their
dependencies.
\row
\o -c or --config directory
\o Use \c directory as the \l{Configuration File}
{config directory}.
\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 --offline-only
\o Create an offline installer that never accesses online
repositories.
\row
\o -v or --verbose
\o Display debug output.
\row
\o -r or --resources
\o Comma-separated list of resources to include in the installer
binary.
\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 directory
\o Use \c directory as the \l{Configuration File}
{config directory}.
\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 --single
\o Place only the specified packages in the repository, without
their dependencies.
\row
\o -v or --verbose
\o Display debug output.
\endtable
*/
/*!
\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:
repogen.exe -p -c repository
For example, to create a repository that contains com.nokia.sdk.qt and
com.nokia.sdk.qtcreator, as well as their dependencies, enter the following
command:
\code
repogen.exe -p packages -c installer-config repository com.nokia.sdk.qt com.nokia.sdk.qtcreator
\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
(confix.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.
\o Required, which determines whether the repository must be available
during the installation.
\endlist
The URL needs to point to the Updates.xml file that lists the available
components. For example:
\code
http://www.yourcompany.com/packages
\endcode
The \a Required setting specifies whether the installer should go ahead even
if it cannot access the server. If you set \c Required to \c true, 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. If you set it to \c false, the
installer continues to work, but excludes any configuration that should
be on the server.
\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 -c installer-config -e com.nokia.sdk.qt,com.nokia.qtcreator SDKInstaller.exe com.nokia.sdk
\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 SDKInstaller.exe com.nokia.sdk
\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{--single} option of repogen.
\section2 Creating Partial Updates
When recreating the online repository, use the \a{--single} 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.
*/