Setup (Windows Installer Bootstrapping)

Native Installer

Document - ID	Specification Owner	Last Change	Status
	Dirk Völzke	29.04.04	draft
Conforms to	
Applies to	Installation
Task ID(s)	i25671
Category	Feature

Abstract

For Windows we need a Setup application (setup.exe) which supports the user in installing the Office. This setup has to check the currently installed version of the Windows Installer and has to install a newer version, if required. Furthermore this setup should offer a language selection dialog for choosing the installation language, if the installation set supports multiple languages.

i-Team Members (The specification owner is part of the i-Team)

	Name	E-mail Address
User Experience	Christian Jansen (CJ)	christian.jansen@sun.com
Development	Dirk Völzke (DV)	dirk.voelzke@sun.com
Quality Assurance	Olaf Felka (OF)	Olaf.felka@sun.com
Documentation	Uwe Fischer	Uwe.Fischer@Sun.com

Approved for Implementation

	Approved by	Date
User Experience	Christian Jansen	29.04.04
Development	Dirk Völzke	27.04.04
Quality Assurance	Olaf Felka	28.04.04
Documentation	Uwe Fischer	27.04.04
String Review		

Document Change History

Rev. Level	Change	Initials	Date
1.0	Initial version	DV	03.02.04
1.1	Applied notes from Uwe Fischer / clean up of 'choose language' dialog	DV	27.04.04
1.2	Applied notes from Christian Jansen	DV	28.04.04

Contents

Glossary	1

1	Motivation	1

2	User Scenarios	1

3	Goals	1

4	Requirements and Dependencies	1

4.1	Requirements	1

4.2	Technical Dependencies	1

5	Competitive Analyses	2

6	Detailed Specification	2

6.1	Command line options:	2

6.2	The 'Usage' dialog:	3

6.3	The 'Update Needed' dialog:	3

6.4	The 'choose language' dialog:	4

6.5	The format of the setup.ini file:	5

6.6	Error Conditions	6

6.7	Migration	6

7	Notes	6

8	References	6

Glossary

Term	Description
msiexec	The Microsoft Windows Installer application

Motivation

When users want to install software on Windows, they need a Windows Installer database containing all information needed for installing. This database could be installed using msiexec with the database file as parameter. But there are different versions of this program available and the user usually doesn't want to use a command line. Therefore OpenOffice.org needs a setup.exe which the user can start with a simple click and which checks the currently installed version of the Windows Installer, offers to install a newer one, if required, displays a 'Choose Language' dialog, if the database file contains support for multiple languages and then calls the msiexec with the appropriate parameters.

User Scenarios

A user installing OpenOffice.org might have no or only an outdated version of the Windows Installer on the computer. It's up to the Setup application to update or install the new version of the Windows Installer choosing the correct version for the users computer ( there are two different versions, one for Windows 98 and Me and one for Windows NT ).

When users install OpenOffice.org using a multi lingual installation set, they have to choose a transformation file containing the language specific part of the installation. The Setup application displays a dialog allowing an easy selection of the installing language and hiding the complex command line options needed to select this language.

Goals

OpenOffice.org used to be installed with it's own installation application, but users demanded the usage of native installers for easier deployment and maintenance. The setup application specified in this document shall provide the user with the standard installation used by most other applications, too.

Requirements and Dependencies

Requirements

The usage of native installers for Windows requires a small application which bootstraps the installation process and hides the complexity of the Windows Installer from the user.

Technical Dependencies

This setup is a Windows only application and shall support Windows 98, Windows Me, Windows NT, Windows 2000 and Windows XP and future Windows versions. For updating the Windows Installer we need the Windows installer redistributables. Because it's a native windows application, it will not support our automatic testing.

Competitive Analyses

The setup application of other products do the same. In [Bob Baker] on page 50 you will find a summary of what should be done during bootstrapping the installation.

Detailed Specification

The setup reads the contents of the file setup.ini beneath it. This file specifies the Windows Installer database file to be installed, the required Windows Installer version., the location of the Windows Installer update files and the in the database available languages. The setup verifies, if the installed Windows Installer version matches the requirements and offers to update / install the Windows Installer if not. When the database contains support for more than one language, the setup displays a 'choose language' dialog. Afterwards the setup launches the Windows Installer with the appropriate parameters. When the setup is launched with parameters, those parameters will be forwarded to the Windows Installer.

Updating or installing the Windows Installer might require administrative privileges, performing an administrative installation requires these privileges, too. When the user doesn't have sufficient privileges, an error box will be shown and the setup application quits.

Command line options:

The Setup supports some of the command line options of the Windows Installer (msiexec). The command line options will be forwarded to the Windows Installer, and there are some options, the setup respects, too. The syntax of the options differ, because the Windows Installer needs the Windows Installer database file specified for some commands whereas the Setup gets this information from the setup.ini file. The options are case insensitive.

Option	Parameters	Meaning
/L	[i|w|e|a|r|u|c|m|o|p|v|x|+|!] logfile	Specifies the path to the log file. '+' append to an existing file All other flags will be ignored but forwarded to msiexec.
/q	[n|b|r|f]	Sets the user interface level. /q and /qn : Silent mode, don't display any UI All other flags will be ignored by the setup but forwarded.
/a		Administrative Installation.
/j	[u|m] [u|m] /t Transform list [u|m] /g Language ID	Advertises product. All other flags will be ignored but forwarded.
/?		Show usage, will not be forwarded.
/i, /f, /p, /x, /y, /z		These options must not be used with the Setup application. If you need these options, use msiexec.
All other		All other options will be ignored but forwarded to msiexec.

When in silent mode, the setup will update the Windows Installer without asking the user, when the installed version doesn't match the requirements.

Advertising ( /j ) will lead to a silent installation, too.

For more information about the command line options of msiexec have a look at the chapter Command Line Options in the Windows Installer SDK documentation.

The 'Usage' dialog:

This dialog is shown when the Setup application is started with the option /?

String list

Item	English	German	Comments
Title	Setup	Setup	Application title
Text	Usage:\n /? : Show this dialog.\n /a : Perform an administrative install.\n /j[u|m] : Perform an advertising install.\n /q[n] : Don't show any User Interface (silent mode).\n	Benutzung:\n /? : Zeigt diesen Dialog.\n /a : Eine Administrative Installation durchführen.\n /j[u|m] : Perform an advertising install.\n /q[n] : Don't show any User Interface (silent mode).\n	
Button	OK	OK	Provoided by windows

The 'Update Needed' dialog:

This dialog pops up, when the user doesn't have the required version of the Windows Installer on his system. When the user selects 'Yes', the setup will install the new version provided with the installation set. Choosing 'No' aborts the whole setup, because we can not continue without the correct version of the Windows Installer. When the user has insufficient rights to install or update the Windows Installer, an error message will be displayed and the setup will be aborted.

String list

Item	English	German	Comments
Title	Setup	Setup	Application title
Text	This package requires a newer version of the Windows Installer. \n Do you want to update the version of the Windows Installer on your system?	Dieser Installationssatz benötigt eine neuere Version des Windows Installers. \n Wollen Sie die vorhandene Version des Windows Installers aktualisieren?	
Button	Yes	Ja	Provoided by windows
Button	No	Nein	Provided by windows

The 'choose language' dialog:

This dialog will only be shown, when there is more than one language specified in the setup.ini file. In this dialog the user can choose the language of the installation program. The dialog will be shown in the language of the system if available or in English. The system language should be preselected if available, the default language specified in the setup.ini file will be used otherwise. When the user selects 'Cancel', the whole installation will be aborted, when the user selects 'OK', the transformation associated with the chosen language will be used to launch the Windows Installer.

CJ: I made some changes to dialog layout.

String list

Item	English	German	Comments
Title	%PRODUCTNAME %PRODUCTVERSIOM Setup	%PRODUCTNAME %PRODUCTVERSIOM Setup	Or 'Choose language' ? CJ-> EM: Please clarify
Text	Please choose the language to be used during the installation:	Bitte wählen Sie die Sprache aus, die während der Installation benutzt werden soll:	
Button	Cancel	Abbrechen	Provided by windows
Button	OK	OK	Provided by windows
Language list	Chinese - Taiwan	Chinesisch - Taiwan	
Language list	Czech	Tschechisch	
Language list	Danish	Dänisch	
Language list	German - Germany	Deutsch - Deutschland	
Language list	Greek	Griechisch	
Language list	English - United States	Englisch – U.S.A.	
Language list	Spanish - Spain	Spanisch - Spanien	
Language list	Finnish	Finisch	
Language list	French - France	Französisch - Frankreich	
Language list	Hebrew	Hebräisch	
Language list	Hungarian	Ungarisch	
Language list	Italian - Italy	Italienisch	
Language list	Japanese	Japanisch	
Language list	Korean	Koreanisch	
Language list	Dutch - The Netherlands	Niederländisch - Niederlande	
Language list	Norwegian - Bokmål	Norwegisch - ???	
Language list	Polish	Polnisch	
Language list	Portuguese - Brazil	Portugisisch - Brasilien	
Language list	Russian	Russisch	
Language list	Slovak	Slovakisch	
Language list	Swedish - Sweden	Schwedisch - Schweden	
Language list	Thai	Thailändisch	
Language list	Turkish	Türkisch	
Language list	Estonian	???	
Language list	Chinese - China	Chinesisch - China	
Language list	Portuguese - Portugal	Portugiesisch - Portugal	

The format of the setup.ini file:

The Setup application needs an setup.ini file located next to the application describing what shall be installed and which languages are available in the installation set. This files contains two sections, [Setup] and [Languages]. The [Setup] sections is mandatory, the [Languages] section is optional.

[Setup]
productname=StarOffice 8	// Name of the product to be installed
database=staroffice8.msi	// location of the database used for installing
instmsiw=instmsiw.exe	// location of the Windows Installer for Windows NT, 2000 and XP
instmsia=instmsia.exe	// location of the Windows Installer for Windows 98 and Me
msiversion=2.0.2600.0	// minimum required version of the Windows Installer

[Languages]
count=2	// Number of languages in this file, mandatory when this section is present
default=1033	// ID of default language, has to be the first entry in this file
lang1=1034,trans_34.mst	// ID of the other languages, including the transform needed for the	Windows Installer
...

All locations in this file ( database, update installers, transformations ) are relative to the Setup application.

An incomplete [Setup] section will lead to an error and the Setup will quit.

Error Conditions

There are a lot of error conditions:

the setup.ini file could not be found (FILE_NOT_FOUND)

the setup.ini file is incomplete or wrong (INVALID_PROFILE)

the MSI installer files are missing (FILE_NOT_FOUND)

the user doesn't have the administrator rights needed for updating the MSI installer (REQUIRES_ADMIN_PRIV) or for performing an administrative installation

invalid command line options specified (INVALID_PARAM)

there is already an instance of the setup application running (ALREADY_RUNNING)

String list

Item	English	German	Comments
FILE_NOT_FOUND	Setup was unable to find the file '%s'.	Das Setup konnte die Datei '%s' nicht finden.	'%s' is a placeholder, please don't translate.
INVALID_PARAM	Invalid command line option '%s'. Please use '/?' for help.	Der Kommandozeilenparameter '%s' ist ungültig. Bitte benutzen Sie '/?' für Hilfe.	'%s' is a placeholder, please don't translate.
ALREADY_RUNNING	There is already a setup process running.	Es läuft bereits ein Setup- Progamm .	
INVALID_PROFILE	Invalid or incomplete profile.	Ungültiges oder unvollständiges Profile.	
REQUIRES_ADMIN_PRIV	Administrator privileges are required for upgrading the Windows Installer.	Es werden Administrator Rechte benötigt, um den Microsoft Windows Installer zu aktualisieren.	

Migration

There are no migration issues with this Setup application.

Notes

##UFI: I've never seen a prompt whether I want to update the installer with a newer version. It will sure be very disturbing for our users if they see such a question. Most possibly many users will cancel the whole installation and ask for help somewhere else. So please make it a "silent" setup by default.

##DV: But that's the way Microsoft does it ( at least in their sample code ).

##UFI: what is an "administrativeinstall" or an "advertising install"? Do we (as users) really need to know? If not, please disable the dialog.

##DV: which dialog? The normal user won't see any dialog ( except the choose language dialog when using a multi language installation ), an advanced user ( using the command line interface ) should have access to the administrative or advertising installation.

CJ: Which is the required version ( in the setup.ini file ): DV: The loader itself doesn't need a specific version.

References

[Bob Baker] The Official InstallShield® for Windows® Installer Developer's Guide, Bob Baker, M&T Books, 2001.

Native Installer Specification

Setup (Windows Installer Bootstrapping)

Page 7

Windows Installer Loader specification

Dirk Völzke

2004-02-19T09:45:24

Dirk Völzke