1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
|
// **********************************************************************
// 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}{InstallerFramework}
\page index.html
\nextpage ifw-globalconfig.html
\title Qt Installer Framework Manual
\section1 Version 1.2.0
The Qt Installer Framework provides a set of tools and utilities to
create installers for all supported desktop Qt platforms.
Tested platforms currently include:
\list
\o Microsoft Windows (Windows XP and following)
\o Linux (Ubuntu 8.04 and following)
\o Mac OS-X (10.6 and following)
\endlist
Those installers can either be stand-alone or download contant from a
networking resource via http transfer. For installers fetching data from
a webserver, tools are available to post install items after the initial
setup as well as update mechanisms are provided as soon as those are
published on the server.
\note Please report bugs in the Nokia Qt SDK bugtracking system
\l{http://bugreports.qt.nokia.com/browse/QTSDK}{here}.
\list
\o Structure of a installer creation setup
\list
\o \l{Global Configuration}
\o \l{Component Description}
\o \l{Included Tools}
\endlist
\o \l{Tutorial}
\o Enhanced instructions
\list
\o \l{Creating online installers}
\o \l{Pure offline installers}
\o \l{Creating updates}
\o \l{Non Interactive Installation}
\endlist
\o \l{Known Issues}
\endlist
*/
/*!
\contentspage index.html
\previouspage index.html
\page ifw-globalconfig.html
\nextpage ifw-component-description.html
\title Global Configuration
For creation of installer binaries and online repositories, you need to
provide a config directory. This directory needs to contain at least a file
named \bold{config.xml} containing XML information about how to build the
installer.
This file can look like this:
\code
<?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>
<Logo>logo.png</Logo>
<License>license.txt</License>
<Watermark>watermark.png</Watermark>
<RunProgram></RunProgram>
<RunProgramDescription></RunProgramDescription>
<StartMenuDir>Some Application Entry Dir</StartMenuDir>
<PublicKey>
-----BEGIN PUBLIC KEY-----
... key values ...
-----END PUBLIC KEY-----
</PublicKey>
<PrivateKey>
-----BEGIN RSA PRIVATE KEY-----
Proc-Type: 4,ENCRYPTED
DEK-Info: DES-EDE3-CBC,C9D3A294C3702C32
... key values ...
-----END RSA PRIVATE KEY-----
</PrivateKey>
<Icon>installericon</Icon>
<!-- @homeDir@ and @rootDir@ are some of the supported vars -->
<TargetDir>@homeDir@/testinstall</TargetDir>
<RemoteRepositories>
<Repository>
<Url>http://www.your-repo-location/packages/</Url>
<Required>false</Required>
</Repository>
</RemoteRepositories>
</Installer>
\endcode
The following settings are contained in this file.
\list
\o \bold{ Name} The name of the product being installed
\o \bold{ Version} The version of the product being installed
\o \bold{ Title} The title text of the generated installer, i.e. its name
\o \bold{ MaintenanceTitle} The title text of the generated maintenance tool, i.e. its name
\o \bold{ Pushblisher} The publisher of the software
\o \bold{ ProductUrl} URL of the product
\o \bold{ Logo} Filename for a logo used as QWizard::LogoPixmap
\o \bold{ License} Filename of the license text to be accepted by the installing user
\o \bold{ Watermark} Filename for a watermark used as QWizard::WatermarkPixmap
\o \bold{ Background} Filename for an image used as QWizard::BackgroundPixmap
\o \bold{ RunProgram} Command executed after the installer is done, if the user accepts it
\o \bold{ RunProgramDescription} Text shown next to the checkbox for running the program. Defaults to "Run <Name>"
\o \bold{ StartMenuDir} Name of the predefined group in the Windows Start Menu
\o \bold{ Icon} Filename of the installer icon. On Windows, .ico is appended, on Mac, .icns is appended and on Linux, .png is appended.
\o \bold{ PublicKey} RSA public key to be used to verify component signatures
\o \bold{ PrivateKey} RSA private key to be used to sign components
\o \bold{ TargetDir} Predefined target directory for installation
\o \bold{ RemoteRepositories} List of remote repositories
\o \bold{ UninstallerName} File name of the generated uninstaller. Defaults to "uninstall". The platform specific executable suffixs is appended.
\endlist
It is suggested that you place all files that are reffered inside the
configuration also into the config directory. However, you can also use
relative paths, which the tools will resolve relative to the location of
the config.xml file.
\bold{Remote Repositories}
The installer configuration file can contain a list of several remote
repositories. Each of them has two properties. The first one is the
repository URL. In the example above, this is
"http://www.your-repo-location/packages/" The URL needs to contain a file
Updates.xml listing the available packages. See \l{Creating online installers}{Online Repository generation}
to read more about online repositories. The second parameter is called
"Required". If you set this to true, the installer won't work if this
repository is not available. In case the repository is accessed after an
installation, this will cause the maintenance tool to reject installation.
However, uninstallation is still possible. If you set it to false, the
installer will continue to work, but exclude any configuration which should
be on the server.
*/
/*!
\contentspage index.html
\previouspage ifw-globalconfig.html
\page ifw-component-description.html
\nextpage ifw-tools.html
\title Component Description
\section1 Documentation on how to create installer components.
The Installer is based on the idea of having several components, which are
either embedded in the installer itself or loaded from a remote repository.
For both, embedding components into the installer and creating an online
repository, you need to keep your components in a certain format readable
by the installer.
\section1 Directory Structure
All components need to be located inside the same root directory, which is
called \bold{package directory}. Components
are identified by a domain-like identifier. This has to be the name of the
directory the component data has to be placed in. Within this directory,
two subdirectories have to exist, called \bold{data} and \bold{meta}.
A package directory can look like this:
\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 Contents of the meta data directory
The meta data directory contains all files which are not to be extracted by
the installer but contain information about deployment and the installation
process.
\section2 package.xml
The file package.xml is the main source of information about the component.
The format of this file is XML and has for instance the following shape:
\code
<?xml version="1.0"?>
<Package>
<DisplayName>QtGui</DisplayName>
<Description>Qt gui libraries</Description>
<Version>1.2.3</Version>
<ReleaseDate>2009-04-23</ReleaseDate>
<Name>com.vendor.root.component2</Name>
<Dependencies>com.vendor.root.component1</Dependencies>
<Virtual>false</Virtual>
<Script>installscript.qs</Script>
<UserInterfaces>
<UserInteface>specialpage.ui</UserInterface>
<UserInteface>errorpage.ui</UserInterface>
</UserInterfaces>
<Translations>
<Translation>sv_se.qm</Translation>
<Translation>de_de.qm</Translation>
</Translations>
</Package>
\endcode
\section3 package value list
\list
\o \bold{DisplayName} The human readable name of the component - required.
\o \bold{Description} The human readable description of the component - required.
\o \bold{Version} The version number of the component needs the following format: [0-9]+((\.|-)[0-9]+)* such as 1-1; 1.2-2; 3.4.7 - required.
\o \bold{ReleaseDate} The day this component version was released - optional.
\o \bold{Name} domain-like identification for this component - required.
\o \bold{Dependencies} Comma-separated list of dependencies - optional.
\o \bold{Virtual} Set to true if this is a virtual component not showing up in the installer.
\o \bold{SortingPriority} Priority of this component when visible in the tree. Lowest priority number is on top.
\o \bold{InstallPriority} Priority of this component when getting installed. Lowest priority number is first.
\o \bold{Script} File name of a script being loaded - optional.
\o \bold{UserInterfaces} One ore more file names of user interfaces being loaded - optional.
\o \bold{Translations} One ore more file names of translations being loaded - optional.
\o \bold{UpdateText} A description added to the component description if the component is an update - optional.
\o \bold{NewComponent} If this flag is set the component appears as an update if its not installed - optional.
\o \bold{Important} The package is marked as important. This is relevant for updates found with UpdateAgent.
\o \bold{ForcedInstallation} This packages must always be installed and can't get unchecked by the user.
\o \bold{AutoSelectOn} Define boolean expressions with other components names to define when this components gets autoselected.
\o \bold{Replaces} Comma-separated list of components to replace - optional.
\endlist
\section2 Additional features
Additonally, all files named in the package.xml - scripts, user interfaces
and translations - have to be in the meta data directory. Referring to
previous example, the directory structure looks like this:
\code
-packages
- com.vendor.root.component2
- data
- meta
- de_de.qm
- errorpage.ui
- installscript.qs
- package.xml
- specialpage.ui
- sv_se.qm
\endcode
\section3 Scripting
Each component can utilize ECMA scripting to perform additional operations
at any time of the installation process. Typical use cases are file
manipulations like moving, copying, patching.
For all full documentation on scripting, see \l{Component Scripting}{here}.
\section3 Component Dependencies
Each component can have one or more components it depends on. This can be
other real or virtual components. Every dependency as defined via its
identifier and optionally its version. The version, if given, is separated
by the identifier by a dash ('-') and can be prefixed by a comparision
operator like '=', '>', '<', '>=' or '<=', which means that the version of
the matching package is compared to the required version and has to be
equal, greater, less, greater or equal or less or equal as the version
number given in the dependency. If no comparision operator is given, it
defaults to '='.
\section3 Component Translation
As the installer makes use of the Qt Translation system, all user readable
output can be translated to other languages. To make this work for strings
contained in component scripts and user interfaces, components can provide
QTranslator files, which get loaded by the installation system when loading
the component. The Installer always loads the translation file with a name
matching the current system locale. For the system locale being German
(Germany), this would be de_de.qm.
Inside of scripts, you have to use the function qsTr() for literal text.
Additionally your script can contain a method Component.prototype.retranslateUi
which is called whenever the language of the Installer has changed, i.e.
after your translation file was loaded.
The context being used for translation is the basename of the script file
when using qsTr or the class name of the UI file when translating an user
interface.
\section3 Component User Interfaces
A component can contain one or more user interface files, which are placed
into the installer by the script. The installer is automatically loading
all ui files listed in the package.xml. You can access the loaded widgets
by calling QInstaller::Component::userInterface with the class name of the
widget:
\code
component.userInterface( "MyPage" ).checkbox.checked = true;
\endcode
There are two ways of inserting custom user interface widgets into the
installer: Inserting them as a single widget or inserting them as their own
page.
To insert them as a single widget, use QInstaller::Installer::addWizardPageItem.
From within the script, this is done by:
\code
// add the instance of MyWidget to the component selection page
installer.addWizardPageItem( component, "MyWidget", QInstaller.ComponentSelection );
\endcode
To add a completely new page into the Installer, you need to specify in
front of which page you want to add it. Adding the page is done with
QInstaller::Installer::addWizardPage.
\code
// add the instance of MyPage in front of the "Ready to Installation" page
installer.addWizardPage( component, "MyPage", QInstaller.ReadyForInstallation );
\endcode
\section2 Contents of the data directory
The data directory contains all the content, which will be extracted during
the installation phasis. There are multiple options of content:
\list
\o Copy all the files into the data location. The directory structure will
be identical between the on in the data location and the installation
directory. Before the installer is created, the included tools will create
a 7zip archive.
\o Create a .7z archive via archivegen, which is included in the Installer
Framework.
\o Place a 7zip compatible archive into the data directory.
\endlist
\note Each of those ways has advantages and disadvantages. From our experience,
using archivegen provides the best solution due to faster creation time
and compatilibility with 7zip.
*/
/*!
\contentspage index.html
\previouspage ifw-component-description.html
\page ifw-tools.html
\nextpage ifw-tutorial.html
\title Included Tools
\section1 installerbase
\bold installerbase 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
Installers are created using binarycreator. This applies to online as well
as offline installers.
In the offline case the component information and their data is appended to
the binary, allowing extraction and post installation scripts to work
without any internet connection.
Online installers store the location of the repository and on startup load
the component information, not the data. Hence binarycreator does only a
partial job in the online case.
You can also create hybrid installers, which store some component locally
and receive others via a network connection. For more information, continue
reading at ###TODO insert link here.
For technical inside on the implementation of data integration into the
installer binary, read the information on QInstaller::BinaryContent ###TODO insert link here.
Please note that changing this configuration requires a recompilation of
installerbase.
\section2 Usage
binarycreator expects the following parameters:
\code
-t or --template file Use file as input file
This is the binary used to append component information.
On Windows, this defaults to be installerbase.exe in the current working directory. On Unix, installerbase is used.
-p or --packages directory Use directory as packaces directory
Specifies the directory to get package, i.e. component information from. See Component Definition to find out how this directory need to look like. This setting defaults to the current working directory.
-n or --nodeps Add only the selected packages to the compile. Don't add their dependencies.
-c or --config directory Use directory as config directory
Specifies the directory to be used for Installer Configuration.
-e or --exclude p1,...,pn Mark a comma separated list of packages to be retrieved from an online repository, i.e. not to be completely included in the installer binary.
-v or --verbose Verbose output. Add this if you are into lots of debug output.
\endcode
These parameters are followed by the name of the target binary and a list
of packages to be availabe for installation. Note that not only these
packages will be inside of the installer, but even all their dependencies
and all packages sharing the same prefix, as long as you add the --nodeps
flag.
On Windows, the name of the target binary is automatically extended with
.exe, if it wasn't already added by the user. On Mac, the target will be
created as application bundle with extension .app, which as automatically
added, if not supplied. Additionally, the user can use a .dmg extension,
which will create a DMG disk image containing an .app bundle.
\section2 Example
\section3 Offline installer
\code
binarycreator.exe -c installer-config SDKInstaller.exe com.nokia.sdk
\endcode
This commands puts com.nokia.sdk as well as all packages com.nokia.sdk
depends on into the installer binary SDKInstaller.exe. Additionally, this
binary will contain all packages prefixed with com.nokia.sdk.*
\section3 Online installer
\code
binarycreator.exe -c installer-config -e com.nokia.sdk.qt,com.nokia.qtcreator SDKInstaller.exe com.nokia.sdk
\endcode
The same as above, except that the data for com.nokia.sdk.qt and
com.nokia.qtcreator will be downloaded from a remote repository.
If your config.xml contains a RSA private key, components and data will be
signed with it. On installer runtime, this signature will be used to verify
the components. Note that the private key is not embedded in the installer
binary. If your private key is protected with a password, you will be asked
to provide the password.
\section2 Platform specific notes
\section3 Mac OS X
If the target binary is suffixed with .app, a shiny Mac OS X application bundle will be created
The icon set in the config.xml is extended with ".icns" and used as icon for a created bundle
\section3 Windows
The icon set in the config.xml is extended with ".ico" and used as application icon for the .exe file.
\section3 Linux
The icon set in the config.xml is extended with ".png" and used as window icon.
\section1 repogen
To generate online repositories, use the tool repogen.
\section2 Usage
repogen expects the following parameters in this order:
\list
\o \bold Packages directory Directory containing the packages. Same as for binarycreator.
\o \bold Configuration directory Directory containing the installer configuration. Same as for binarycreator.
\o \bold Repository directory Target directory to generate the repository. Must not yeut exist.
\o \bold Components List of components to be placed into the repository. Includes dependencies.
\endlist
If your config.xml contains a RSA private key, components and data will be
signed with it. On installer runtime, this signature will be used to verify
the components. Note that the private key is not put into the repository.
If your private key is protected with a password, you will be asked to
provide the password.
When the repository has been created, you can upload it to anywhere. Just
put the location into the installer configuration when creating an installer
for it.
\section3 Example
\code
repogen.exe packages installer-config repository com.nokia.sdk.qt com.nokia.sdk.qtcreator
\endcode
This command creates a repository inside of repository containing
com.nokia.sdk.qt and com.nokia.sdk.qtcreator, including all dependencies.
*/
/*!
\contentspage index.html
\previouspage ifw-tutorial.html
\page ifw-online-installers.html
\nextpage ifw-offline-installers.html
\title Creating online installers
\section1 Configuration changes
Online installers fetch the repository description in addition to the one
stored inside of the binary. The technical effort is very little. Inside
the global \a{config.xml} file, you need to add the location of your
repository like this:
\code
<RemoteRepositories>
<Repository>
<Url>http://www.yourcompany.com/repository</Url>
<Required>false</Required>
</Repository>
</RemoteRepositories>
\endcode
The \a Required tag describes, if the installer should go forward even
without accessing the server.
\section2 Creating the binaries
You will not need to change any of the arguments to create installer
binaries. The process of creating installer binaries is documented
\l{binarycreator}{here}.
\section2 Reducing the size of online installers
Even if a remote location is specified, this does not exclude the
components to be added to the installer binary itself. This results
in a bigger installer binary, which checks for the online repository.
This has the advantage, that if no newer version is available on the
server, the user will spare the additional download.
However, this is sometimes not the desired scenario. Instead the online
installer should not contain any data and fetch all its data from the
network connection.
To achieve this, use the \a{-n} parameter of binary creator 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
and a list of available options, please refer to \l{binarycreator}{here}.
*/
/*!
\contentspage index.html
\previouspage ifw-online-installers.html
\page ifw-offline-installers.html
\nextpage ifw-updates.html
\title Pure offline installers
Pure offline installers describe the scenario in which the installer
does not try to connect to an online repository at all during the install
step. However, post installation as well as receiving updates will use
the description stored in the meta configuration (\a{config.xml}).
This is especially useful in cases where a corporate firewall does not
allow to connect to servers, but a successful installation is demanded.
To create such installers, \l{binarycreator} has the \a{--offline-only}
option which will output a installation binary with above settings.
*/
/*!
\contentspage index.html
\previouspage ifw-offline-installers.html
\page ifw-updates.html
\nextpage ifw-knownissues.html
\title Creating updates
Creating online installers has the advantage that updates can be promoted
to the users who have the product installed. This section describes the
steps to promote an update.
\section1 Configuration changes
The maintenance/updater tool downloads the update description on startup
and then compares the installed version with the promoted one on the server.
If the online version number is greater than the local one, the component
is displayed in the list of available updates.
To achieve this, the \a{Version} tag of the components needs to be increased.
\section1 Recreating the repository
The easiest solution to provide an update is to recreate the online
repository and then upload it to the server location. This can be achieved
by reusing \l{repogen}.
\section1 Partial updates
\section2 Scenario description
Sometimes a full update of the whole repository might not be welcomed. The
reasons might be
\list
\o The size of the repository is very big, so that uploading takes a
significant amount of time
\o Updates need to be provided to a separate entity, where only changed
elements should be delivered to.
\endlist
\note repogen recreates the 7zip archives each time it is being called. As
7zip stores the timestamp of included files (which get moved/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 to the
7zip. As the SHAs are stored inside the global \a{Updates.xml} you will be
forced to upload the full repository. This can be circumvented by using the
\a{--single} option of repogen.
\section2 Implementation
When recreating the online repository, use the \a{--single} parameter. This
takes an existing repository as input and only changes the components,
which are specified as additional parameters. Only those SHA sums will be
changed in the global configuration as well.
\section3 Uploading partial updates
Assuming the repository has been updated like in above description, you will
not have to upload the whole repository again. Instead only the following
items are required:
\list
\o The component directory (usually something alike
\a{com.vendor.foo.updatedpart}.
\o The global \a{Updates.xml} stored in the root directory of the online
repository.
\endlist
\note The order of uploading is very important. In case you update the
repository on a live server, you should first update the component and
only afterwards the xml configuration. As the archive names include the
versioning the user will be provided with the old package until the update
has finished.
*/
/*!
\contentspage index.html
\previouspage ifw-updates.html
\page ifw-knownissues.html
\nextpage index.html
\title Known Issues
Some of the items can be seen on the Nokia Qt SDK bugtracking system
\l{http://bugreports.qt.nokia.com/browse/QTSDK}{here}.
*/
|