sec28.html

28 Programming with the Setup Utility

The TRUET_EX Setup program is our own custom application, and should not be confused with the Microsoft Setup Toolkit programs, InstallShield, or other third-party installers. It is a small, quick, and versatile executive for the installation process, and supports font installation, which many install utilities do not. This section is a detailed guide to using Setup and a guide for experts programming Setup for use with other applications.

28.1 How Setup Organizes Distribution Disks

TRUET_EX Setup uses a file called manifest on the first Setup disk as a script to guide the installation process. You can examine this text file for details on what happens during installation but is ordinarily hidden from view. You can modify the manifest file to create a custom Setup for networked or site-licensed copies (assuming you have paid the appropriate royalties to us to legally make internal copies of TRUET_EX, of course).

28.2 Modifying Setup for Network-Master Installation

You can make a master network copy of the TRUET_EX installation resources on any host file server; from this master copy any user on the network could install TRUET_EX on a given system. Such a master copy simply consists of all the files on the TRUET_EX setup disks, which you copy into a single directory on the file server. Networked users can then run the Setup program from the file server's copy instead of from floppy diskettes. Setup and the manifest file do not depend on any particular arrangement of files on the Setup disks and will automatically adapt to the situation where all the files for installation are located together in a network file server directory.

28.3 Setup command-line syntax

Setup recognizes the following command-line syntax:

setup [opts] Use this form for a ``first pass'', that is, there are no arguments, and no -u option. After loading the manifest (which is not acted upon in the first pass other than to check syntax and note command-line options), displays a welcome message (unless -s is in effect), invokes an installation destination dialog (unless -f given), copies itself to the destination directory, and launches the ``clone'' with ``second pass'' arguments described below. The cloning is necessary because the executable file on the floppy disk (which floppy will possibly be removed and replaced with another during the installation process) cannot be removed during installation. If -u is in the options, the invocation is for an un-installation (see below).

setup [opts] src dest This form is a ``second pass,'' and is usually only used by the first pass to pass information to the ``cloned'' copy. Installs from files from the src directory to the dest directory using a manifest file (default name is ``manifest'' or other value from the -m option) relative to src directory. Not a valid form for un-installation (-u).

Command-line options are as follows. Certain options must precede others to take effect. The option arguments may not contain spaces; thus a there is a limitation on WIN32 long file names (they cannot contain spaces).

-v: Toggles verbose mode, which is useful for debugging.

-s: Toggles installation silent mode, which omits routine messages, and only displays messages when errors occur. Use with -f if you want absolutely no messages in the absence of errors; otherwise a target-directory selection dialog will still appear. Using -v will override -s. Silent mode does not affect un-installs very much; we feel that the user should know and confirm when things are being removed from his system.

-q: Like -s silent mode, except for un-installation. Use with caution.

-p name: Uses product name name in dialogs. Title bars in windows will show this, followed by ``Setup'' (or ``Un-Install'' if -u preceded). It will also be used as the ``Start Menu'' subdirectory for installation/un-install.

-d dest: Uses dest as the default destination (target) directory for installation or un-installation. This is the initial value that will appear in the user dialog prompting for the target directory, or giving notice of a mandatory target directory, if the -f option is given, where the installation/un-installation will begin (the dialog or notice will not appear if -s is given). Not valid for 2nd pass invocation.

-m manif: Uses manif as the starting manifest file name. This is valid during 1st or 2nd pass invocation or un-install. The 1st pass does not load the manifest, but will pass along the name in a -m argument to the 2nd pass invocation, where it will be loaded and used without further notice.
You can specify more than one manifest file name by separating them with commas, such as ``-m execs,fonts'' specifying that files execs and fonts in the source (during install) or target (during un-install) directory will be used as starting manifests. Manifests can in turn call other manifests in a nested fashion; see the TRUET_EX ``manifest'' file comments for a description of the format.
Note that Setup will compute a full path name of the manifest file which is the concatenation of the source directory with the manifest file name (default manifest or -m value) during an installation (that is, -u was not specified), or the destination directory (that is, -u was specified). To specify such a destination directory during un-installation, use -d, and perhaps -f.
It is your responsibility as the setup media creator to make sure the manifest is present in the source directory on the installation media for installation files, and that the the installation manifest installs a suitable un-installation manifest into the target directory (assuming you want to provide an un-install feature).
Manifest script files can direct Setup to install or un-install software with a number of actions, described fully in the TRUET_EX manifest file on TRUET_EX Setup Disk 1. Actions can create sub-directories of the target directory, make any of those directories the current working directory, execute programs from the source media (typically self-extracting archives), copy and remove files directly by name, stream-edit text files to replace placeholder strings with the target directory (useful for creating customized .INI files), send DDE commands to the Windows program manager to create and populate program groups in the Start Menu, and verify that the run-time environment is a proper version of Windows, and load other manifest files.
Setup loads the entire manifest into memory from one or more manifest files and closes the files before starting to perform the manifest actions. Besides checking the syntax of the manifest, this permits the manifest files to originate on removable media volumes that are switched during the installation process.

-f: The destination directory (default or -d destination) is fixed. The user will not be presented a dialog offering a chance to change the default. Not valid for 2nd pass invocation.

-u: Un-installs: invokes an installation destination dialog, and uses file name manifest in the destination directory (or another manifest name relative to the destination with the -m option) to un-install files and fonts. You probably should use -d with this to specify where the application's un-install manifest resides, since the usual convention is to name the installation (not un-install) manifest with the name ``manifest''. Use -p, too, before the -u. Do not use source and destination arguments with the un-install option; the un-install invocation should contain only dashed options.
An un-installation manifest may be unable to directly delete certain files, such as executables files that are running (the setup.exe program itself, for example) or fonts that have been opened and locked by the operating system. The un-install mode of Setup will schedule such files for deletion on the next system re-start, using either the Windows 95 WININIT method or the Windows NT MoveFileEx method, as is appropriate to the run-time environment.
The reasonable expection of a user is that an application's un-install manifest is a ``mirror image'' of the installation. That is, the un-install manifest should list all the files and fonts that the installation originally created.
It is not an error, nor will a message appear, if a file to be removed by a manifest is not present or a font to be unregistered is not registered. This allows you to create a global un-installation manifest that covers the whole application, even though you may only have installed part of it. You can also create manifests which will register and un-register sets of fonts in the Windows system, without altering the underlying TrueType font files.
Un-install manifests should unregister fonts before removing the corresponding TrueType files. This order is not important in most situations, however, as the same result will exist after a system re-start.
The un-install mode of Setup has no provision to remove directories. This means application directories, perhaps empty, will always remain despite un-installation. You should advise the user that he should examine the vestigial directories for any critical files that might remain (such as documents that might have been created in the TRUET_EX application directory tree), and that he should manually remove directories using the Windows Explorer or other method when he is satisfied that they are empty.
Option -u is not valid in a 2nd-pass invocation.

28.4 Other Setup Programming Considerations

You can create various sub-manifests for components of your application, and invoke Setup with combinations of them for customized installations, with the link `l' manifest action.

Later versions of setup.exe ( TRUET_EX releases 4.1E and later) provide a `u' manifest action which will unzip archives using the UNZIP32.DLL library. Formerly, Setup called on self-extracting executable archives to unzip themselves; these were DOS programs and lacked some grace in running under Windows. The new, native unzipping ability in Setup means that the entire process runs in a controlled, 32-bit Windows environment.

Distribution media for use with Setup should contain not only setup.exe and the installation manifest (and possibly sub-manifests called by the starting manifest, depending on your design), but also UNZIP32.DLL if the manifest calls for unzipping (`u') actions. If your manifest uses ``x'' actions (now obsolete; use unzipping instead), then you must also include execfrom.exe and execfrom.pif. An un-installation manifest is strongly recommended. These recommendations imply that the installation manifest should begin with ``c'' actions for these auxiliary files (but not setup.exe itself, which Setup must copy itself before the manifest is loaded).

28.5 Examples of Using Setup

`a:setup`	Does an interactive install of TRUET_EX.
`a:setup -p Blatz -d C:\Blatz`	Does an interactive install of ``Blatz''.
`a:setup -s -f -d C:\TrueTeX -m manifest`	Installs to a known directory, silently.
`c:\TrueTeX\setup -u -f -d C:\TrueTeX -m uninstal`	Un-installs from a known directory, `C:\TrueTeX`.

HEAD