\documentstyle[a4,makeidx,verbatim,texhelp,fancyhea,mysober,mytitle]{report}%
%\input psbox.tex%
\parskip=10pt%
\parindent=0pt%
\winhelpignore{\title{Manual for wxWindows Install 1.03:\\A simple Windows installation utility}%
\author{Julian Smart\\Artificial Intelligence Applications Institute\\%
University of Edinburgh\\EH1 1HN}%
\date{April 1995}%
}%
\winhelponly{\title{Manual for wxWindows Install 1.03}%
\author{by Julian Smart, Artificial Intelligence Applications Institute, %
University of Edinburgh\\}%
}%
\makeindex%
\begin{document}%
\maketitle%
\pagestyle{fancyplain}%
\bibliographystyle{plain}%
\pagenumbering{roman}%
\setheader{{\it CONTENTS}}{}{}{}{}{{\it CONTENTS}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%
\tableofcontents%

\chapter*{Copyright notice}%
\setheader{{\it COPYRIGHT}}{}{}{}{}{{\it COPYRIGHT}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%

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.

\chapter{Introduction}%
\pagenumbering{arabic}%
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%

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 {\it 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 {\it
compress.exe} program found in the wxWindows Install {\bf bin}\rtfsp
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 {\bf docs} directory: use this as a
template for your own files.

\section{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.

\chapter{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:

\begin{verbatim}
ftp.aiai.ed.ac.uk
\end{verbatim}

in the directory /pub/packages/wxinstall.

\chapter{Change log}

Changes in version 1.06 (June 1995):

\begin{itemize}
\item Fixed bug where some program manager items would not be
added, because the items were being read wrongly from the install.inf file
(something strange going on with reading entries with commas in the key).
\item Increased maximum number of Program Manager items to 60.
\end{itemize}

Changes in version 1.05 (June 1995):

\begin{itemize}
\itemsep=0pt
\item Now you can put WINDOWSDIR into destination directories.
\end{itemize}

Changes in version 1.04:

\begin{itemize}
\itemsep=0pt
\item Prerequisites section and WINDOWSDIR keyword added (thanks to Stefan Schwarz).
\end{itemize}

Changes in version 1.03:

\begin{itemize}
\itemsep=0pt
\item Bug cured: entering a different path wasn't reflected properly
in the program manager group items.
\item Bug cured: path delimiters getting repeated if source is a root path
(e.g. on a floppy disk).
\item Message in an execution entry can have special characters;
the right-hand side can now be blank.
\item 1,N syntax added for file groups, for specifying groups not needing
installation by default.
\item If external decompression command fails, gives error message.
\end{itemize}

Changes in version 1.02:

\begin{itemize}
\itemsep=0pt
\item Now checks if the destination directory is the same
as the source, and doesn't allow it.
\item /v on the command line pops up a version message.
\item Amount of free space required now shown to user.
\item Decompressors section allows specification of
externally-invoked decompression programs. Useful for
when your program doesn't {\it quite} fit on a disk with the
standard compression method. The downside is user-unfriendly
screen mode changing (for DOS methods).
\end{itemize}

Changes in version 1.00:

\begin{itemize}
\itemsep=0pt
\item First release.
\end{itemize}

\chapter{Bug list}

\begin{itemize}
\itemsep=0pt
\item Could use a little more install.inf error checking.
\end{itemize}

\chapter{Possible future enhancements}

\begin{itemize}
\itemsep=0pt
\item Ability to substitute directories in text files (e.g. .INI files).
\item Option to edit the media source path.
\item An uninstall option.
\item 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.
\item Hooks for user-supplied code.
\end{itemize}

\chapter{The INSTALL.INF file format}%
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%

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.

\section{Sections}

\subsection{Application}

The Application section should have the following entries.

\begin{twocollist}\itemsep=0pt
\twocolitem{Name}{The name of the program being installed.}
\twocolitem{Title}{The title to be placed in the installation program's title bar.}
\twocolitem{Directory}{The default destination directory on the hard disk.}
\twocolitem{PM Group}{The program manager group name.}
\twocolitem{Free Space}{The amount of free space required. This is not explicitly
checked, but will be presented to the user.}
\end{twocollist}

For example:

\begin{verbatim}
[Application]

Name=Test
Title=Test Installation
Directory=c:\testit
PM Group=TestIt
Free Space=1000          ; in kbytes
\end{verbatim}

\subsection{Decompressors}\label{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:

\begin{itemize}\itemsep=0pt
\item \verb${SRCDIR}$ The source directory specified for this file.
\item \verb${DESTDIR}$ The destination directory specified for this file.
\item \verb${SRCFILE}$ The source filename specified for this file.
\item \verb${DESTFILE}$ The destination directory specified for this file.
\item \verb${WINDOWSDIR}$ The user's Windows directory.
\item \verb${N}$ N is an integer between 1 and 9 representing a
destination directory as mentioned in the Directories section.
\item \verb$(N)$ N is an integer between 1 and 9 representing a
source directory as mentioned in the SourceDirs section.
\end{itemize}

Example:

\begin{verbatim}
[Decompressors]

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

\subsection{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.

\begin{verbatim}
[Disks] 

1=Test Install Disk
\end{verbatim}

\subsection{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:

\begin{verbatim}
[Directories] 

1=.
2={WINDOWSDIR}system
3=.\docs
\end{verbatim}

Note the third kind of syntax: directories below the main destination directory should
be written like this. Otherwise, the directory will be taken to be an absolute path.

\subsection{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.

\begin{verbatim}
[SourceDirs] 

1=.
\end{verbatim}

\subsection{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.

\begin{verbatim}
[FileGroups] 

1=Main Program Files
2,N=Demo files
\end{verbatim}

\subsection{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:

\begin{itemize}
\itemsep=0pt
\item Source file name
\item Destination file name
\item Source directory number (corresponding to an entry in the SourceDirs
section)
\item 0 (zero)
\item Disk number (corresponding to an entry in the Disks section)
\item Y or N specifying compression or no compression (internal method).
Instead of Y, you can specify a name as found in the \helpref{Decompressors}{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.
\end{itemize}

For example:

\begin{verbatim}
[Windows Files]

CTL3D Library=ctl3dv2.dll ctl3dv2.dll 1 0 1 N
\end{verbatim}

\subsection{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:

\begin{itemize}
\itemsep=0pt
\item Source file name
\item Destination file name
\item Source directory number (corresponding to an entry in the SourceDirs
section)
\item Destination directory number (corresponding to an entry in the Directories
section)
\item Disk number (corresponding to an entry in the Disks section)
\item Y or N specifying compression or no compression (internal method).
Instead of Y, you can specify a name as found in the \helpref{Decompressors}{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.
\end{itemize}

For example:

\begin{verbatim}
[Files1]

ReadMe=readme.txt readme.txt 1 1 1 N
Test File=test.zip test.txt  1 1 1 PKZIP
\end{verbatim}

\subsection{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:

\begin{verbatim}
[PM Group] 

Read Me,progman.exe,28=notepad.exe {1}readme.txt
Test File=notepad.exe {1}test.txt
\end{verbatim}

\subsection{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 \helpref{Decompressors}{decompressors} section for
valid keywords.

\begin{itemize}\itemsep=0pt
\item \verb$\n$ Carriage return (you need to write \verb$\r\n$ for a line break)
\item \verb$\r$ Line feed
\item \verb$\t$ Tab
\item \verb$\\$ Backslash
\item \verb$\-$ Equals
\end{itemize}

\begin{verbatim}
[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
\end{verbatim}

\subsection{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:

\begin{itemize}\itemsep=0pt
\item \verb$\n$ Carriage return (you need to write \verb$\r\n$ for a line break)
\item \verb$\r$ Line feed
\item \verb$\t$ Tab
\item \verb$\\$ Backslash
\item \verb$\-$ Equals
\end{itemize}

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

\begin{verbatim}
[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
\end{verbatim}

\section{Example INSTALL.INF file}

\begin{verbatim}
; 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
\end{verbatim}

\rtfonly{\printindex%
\setheader{{\it INDEX}}{}{}{}{}{{\it INDEX}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%
}%

\end{document}