Contents
Manual for wxWindows Install 1.03

by Julian Smart, Artificial Intelligence Applications Institute, University of Edinburgh

Contents

Copyright notice

Introduction

Obtaining wxWindows Install

Change log

Bug list

Possible future enhancements

The INSTALL.INF file format


Copyright notice

Copyright (c) 1995 Julian Smart.

Permission to use, copy, modify, and distribute this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice, author statement and this permission notice appear in all copies of this software and related documentation.

THE SOFTWARE IS PROVIDED "AS-IS'' AND WITHOUT WARRANTY OF ANY KIND, EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

IN NO EVENT SHALL JULIAN SMART OR THE ARTIFICIAL INTELLIGENCE APPLICATIONS INSTITUTE OR UNIVERSITY OF EDINBURGH BE LIABLE FOR ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.


Introduction

This document describes wxWindows Install, a simple installation utility for Windows. Although it is distributed as part of the wxWindows project, it can be used for installing any relatively simple Windows application.

The standard Microsoft Setup toolkit, although very flexible, is extremely complex to understand and use. It also requires you to distribute many DLLs and files on your installation disk that may almost fill the first disk, forcing you to use two disks where one would suffice. For simple installation needs that do not need the power of the Microsoft toolkit, a free alternative is required.

It is possible to produce an installation disk in a matter of minutes, with no coding involved. For special installation needs, it's possible you might want to add code to the standard program, but most projects will not require it.

All you do is produce an install.inf file detailing the files being distributed, Program Manager icons, what to run after installation, etc. Then distribute your files along with install.exe, install.inf. The user runs install.exe which reads install.inf, offers some choices of destination directory and file groups to install, and proceeds with the copying, decompressing, and optional creation of a Program Manager group and icons. If disk changes are needed, the user will be prompted.

You may have some DLLs which must be copied to the Windows system directory: this can be specified in install.inf. This way, there will not be the confusion that typically surrounds the installation of programs that require CTL3DV2.DLL and other such DLLs.

Some of the files will typically be compressed using Microsoft's compress.exe program found in the wxWindows Install bin directory. If this compression method is not sufficient, you can specify your own DOS or Windows compression program to execute.

See the example install.inf in the docs directory: use this as a template for your own files.

A couple of notes about the implementation


Obtaining wxWindows Install

wxWindows Install is included in the main wxWindows distribution.

The latest version of wxWindows Install can be accessed separately by anonymous ftp from:

ftp.aiai.ed.ac.uk

in the directory /pub/packages/wxinstall.


Change log

Changes in version 1.05 (June 1995):

Now you can put WINDOWSDIR into destination directories.

Changes in version 1.04:

Prerequisites section and WINDOWSDIR keyword added (thanks to Stefan Schwarz).

Changes in version 1.03:

Bug cured: entering a different path wasn't reflected properly in the program manager group items.

Bug cured: path delimiters getting repeated if source is a root path (e.g. on a floppy disk).

Message in an execution entry can have special characters; the right-hand side can now be blank.

1,N syntax added for file groups, for specifying groups not needing installation by default.

If external decompression command fails, gives error message.

Changes in version 1.02:

Now checks if the destination directory is the same as the source, and doesn't allow it.

/v on the command line pops up a version message.

Amount of free space required now shown to user.

Decompressors section allows specification of externally-invoked decompression programs. Useful for when your program doesn't quite fit on a disk with the standard compression method. The downside is user-unfriendly screen mode changing (for DOS methods).

Changes in version 1.00:

First release.


Bug list

Could use a little more install.inf error checking.


Possible future enhancements

Ability to substitute directories in text files (e.g. .INI files).

Option to edit the media source path.

An uninstall option.

More fancy user interface (but this may start to increase the size of install.exe to an undesirable extent). See other installation procedures for ideas.

Hooks for user-supplied code.


The INSTALL.INF file format

The install.inf file uses standard Windows .INI file syntax, with section names enclosed in square brackets and zero or more entries in each section. Comments may be used, starting with a semi-colon and continuing to the end of the line.

Sections

Example INSTALL.INF file


A couple of notes about the implementation

One possibility for the wxWindows project would be to write a generic program using the wxWindows API. Unfortunately, this would result in a program hundreds of KB in size, competing for disk space with the program that is to be distributed. Also, since installation needs differ widely from platform to platform, it makes sense to code each platform's installation program individually.

wxWindows Install has therefore been written in native Windows, and is consequently around 41 KB in size.

The INSTALL.INF format is not an original file format. It is based on an existing installation utility file format, but I don't think that the format itself is copyright. All the code is original, written from scratch with no reference to any other code, and some extensions have been made to the file format to allow enhanced functionality.


Sections

Application

Decompressors

Disks

Directories

SourceDirs

FileGroups

Windows Files

FilesN

PM Group

Prerequisites

Execution


Example INSTALL.INF file

; Test installation script

[Application]

Name=Test

Title=Test Installation

Directory=c:\testit

PM Group=TestIt

Free Space=1000          ; in kbytes

[Decompressors]

GZIP={SRCDIR}\gzip.exe -f -d {SRCDIR}\{SRCFILE} >> {DESTDIR}\{DESTFILE}

PKUNZIP={SRCDIR}\pkunzip.exe -d {SRCDIR}\{SRCFILE} {DESTDIR}

[Disks]

1=Test Install Disk

[Directories]

; List of destination directories (under the main destination directory).

1=.

[SourceDirs]

; List of directories on the source disks.

1=.

[FileGroups]

; List of file groups, max 5.

1=Main Program Files

[Windows Files]

; Files to be installed in \windows\system.

;

; <description>=<source name> <dest name> <sourcedir #> <0> <disk #> <Y | N>

;

; The last parameter specifies compression (yes or no)

;

CTL3D Library=ctl3dv2.dl$ ctl3dv2.dll 1 0 1 Y

[Files1]

;

; <description>=<source name> <dest name> <sourcedir #> <destdir #> <disk #> <Y | N>

;

; The last parameter specifies compression (yes or no)

;

ReadMe=readme.txt readme.txt 1 1 1 N

Test File=install.inf install.inf     1 1 1 N

[Prerequisites]

; Zero or more items which should be checked before installation

;

;

;  [A] [?] ['message']=<file>

;  A:       Abort if file can't be found

;  ?:       Ask user to proceed

;  message:	Message to be displayed if file can't be found

;  file:    file to be looked up (special symbols see COMPRESSORS)

;

;A?'Previous version not correctly installed\nDo you want to proceed'={1}readme.txt

A?'There seems to be no win.ini file :-( '={WINDOWSDIR}win.ini

[PM Group]

; Zero or more items to go in the Program Manager (or other

; shell) group.

;

; <Item title> [,<executeable>,<icon index>]=<command spec>

;

; E.g.

;

; Read Me,progman.exe,28=notepad.exe {1}readme.txt

; Changes=notepad.exe {1}test.txt

Read Me,progman.exe,28=notepad.exe {1}readme.txt

Test File=notepad.exe {1}test.txt

[Execution]

; Zero or more program specifications.

;

; [W][?]['<Message>']=<command spec>

;

; W:            Wait for program termination

; ?:            Ask yes/no

; Message:      Message in message box

; Command spec: Command line, where {n} is replaced by directory

;

; E.g.

;

; W=notepad {1}readme.txt                           ; Wait for termination

; W?'Read the ReadMe now?'=notepad {1}readme.txt    ; Ask if execute

; 'Read this file carefully!'=notepad {1}readme.txt ; Messagebox, then execute

; dummy=notepad {1}readme.txt                       ; No message, just execute

W?'Read the ReadMe now?'=notepad.exe {1}readme.txt


Application

The Application section should have the following entries.

Name	The name of the program being installed.

Title	The title to be placed in the installation program's title bar.

Directory	The default destination directory on the hard disk.

PM Group	The program manager group name.

Free Space	The amount of free space required. This is not explicitly checked, but will be presented to the user.

For example:

[Application]

Name=Test

Title=Test Installation

Directory=c:\testit

PM Group=TestIt

Free Space=1000          ; in kbytes


Decompressors

The optional Decompressors section allows the specification of external decompression programs, to be used instead of the internal decompression method.

Each entry is a name which will be used in a file group entry, and the value is a command containing a number of keywords that will be filled in by the installation program.

These keywords are:

{SRCDIR} The source directory specified for this file.

{DESTDIR} The destination directory specified for this file.

{SRCFILE} The source filename specified for this file.

{DESTFILE} The destination directory specified for this file.

{WINDOWSDIR} The user's Windows directory.

{N} N is an integer between 1 and 9 representing a destination directory as mentioned in the Directories section.

(N) N is an integer between 1 and 9 representing a source directory as mentioned in the SourceDirs section.

Example:

[Decompressors]

GZIP={SRCDIR}\gzip.exe -f -d {SRCDIR}\{SRCFILE} >> {DESTDIR}\{DESTFILE}

PKUNZIP={SRCDIR}\pkunzip.exe -d {SRCDIR}\{SRCFILE} {DESTDIR}


Disks

The Disks section should have entries consisting of an integer key, and string value naming the disk. There should be at least one disk entry, e.g.

[Disks]

1=Test Install Disk


Directories

The Directories section should have entries consisting of an integer key, and string value naming the destination directory which will be placed under the main application destination directory.

There should be at least one entry.

Example:

[Directories]

1=.

2={WINDOWSDIR}system


SourceDirs

The SourceDirs section should have entries consisting of an integer key, and string value naming the source directory.

There should be at least one entry, e.g.

[SourceDirs]

1=.


FileGroups

The FileGroups section should have entries consisting of an integer key, and a string value naming a file group. A file group is a category of files that the user can choose to install. If there is only one file group, the user will not be offered an option to install the group.

If you wish to have the file group not be installed by default, specify N after the file group number, as in the example below. Y specifies that the group be installed by default.

There should be at least one entry, e.g.

[FileGroups]

1=Main Program Files

2,N=Demo files


Windows Files

The Windows Files section should have entries consisting of a unique name, and a string value consisting of various fields.

The Windows Files section details files which should be copied to the Windows system directory.

The value consists of fields as follows:

Source file name

Destination file name

Source directory number (corresponding to an entry in the SourceDirs section)

0 (zero)

Disk number (corresponding to an entry in the Disks section)

Y or N specifying compression or no compression (internal method). Instead of Y, you can specify a name as found in the Decompressors section. In this case, the external method will be invoked. Some other methods give better compression ratios, which can be crucial when trying to fit files onto a minimal number of disks.

For example:

[Windows Files]

CTL3D Library=ctl3dv2.dll ctl3dv2.dll 1 0 1 N


FilesN

The FilesN sections, where N is between 1 and 5, should have entries consisting of a unique name, and a string value consisting of various fields.

The FilesN section details files which should be copied to a destination directory.

The value consists of fields as follows:

Source file name

Destination file name

Source directory number (corresponding to an entry in the SourceDirs section)

Destination directory number (corresponding to an entry in the Directories section)

Disk number (corresponding to an entry in the Disks section)

Y or N specifying compression or no compression (internal method). Instead of Y, you can specify a name as found in the Decompressors section. In this case, the external method will be invoked. Some other methods give better compression ratios, which can be crucial when trying to fit files onto a minimal number of disks.

For example:

[Files1]

ReadMe=readme.txt readme.txt 1 1 1 N

Test File=test.zip test.txt  1 1 1 PKZIP


PM Group

The PM Group section specifies the icons to be placed in the Program Manager group (if any).

The key can be a name, or a name with program containing an icon, together with an integer icon index. The icon index specifies an icon to extract from with the program (the example below extracts icon number 28 from progman.exe, showing a more attractive icon than the standard nodepad icon). Omitting the executable and icon index will cause the first icon in the command's executable to be used.

The value is a command, with N (where N is an integer between 1 and 5) being replaced by a directory name from the Directories section.

For example:

[PM Group]

Read Me,progman.exe,28=notepad.exe {1}readme.txt

Test File=notepad.exe {1}test.txt


Prerequisites

The Prerequisites section specifies files that should be present before file copying starts.

See the example below for the key and value syntax. The message may contain the following sequences which are passed to the Windows message box appropriately:

See also the Decompressors section for valid keywords.

\n Carriage return (you need to write \r\n for a line break)

\r Line feed

\t Tab

\\ Backslash

\- Equals

[Prerequisites]

; Zero or more items which should be checked before installation

;

;

;  [A] [?] ['message']=<file>

;  A:       Abort if file can't be found

;  ?:       Ask user to proceed

;  message:	Message to be displayed if file can't be found

;  file:    file whose existance should be checked (special symbols see Decompressors)

;

;A?'Previous version not correctly installed\nDo you want to proceed'={1}readme.txt

A?'There seems to be no win.ini file :-( '={WINDOWSDIR}win.ini


Execution

The Exection section specifies the command(s) to be executed at the end of installation.

See the example below for the key and value syntax. The message may contain the following sequences which are passed to the Windows message box appropriately:

\n Carriage return (you need to write \r\n for a line break)

\r Line feed

\t Tab

\\ Backslash

\- Equals

The command can be omitted, in which case the message box will be displayed but no command executed.

[Execution]

; Zero or more program specifications.

;

; [W][?]['<Message>']=<command spec>

;

; W:            Wait for program termination

; ?:            Ask yes/no

; Message:      Message in message box

; Command spec: Command line, where {n} is replaced by directory

;

; E.g.

;

; W=notepad {1}readme.txt                           ; Wait for termination

; W?'Read the ReadMe now?'=notepad {1}readme.txt    ; Ask if execute

; 'Read this file carefully!'=notepad {1}readme.txt ; Messagebox, then execute

; dummy=notepad {1}readme.txt                       ; No message, just execute

W?'Read the ReadMe now?'=notepad.exe {1}readme.txt