Winstall User's Guide Version 1 Introduction ============ Winstall automatically installs software packages by copying files from one or more source diskettes onto your customer's system. Winstall simplifies the installation process and reduces the chance that your customer will incorrectly install your software package. Features ======== * Supports installation to hard disk or floppy diskette * Maximizes use of memory during installation to reduce floppy swapping * Supports multiple source disk installations, and prompts the user to insert disks as needed * Automatically creates directories as needed on the destination disk * Can patch the installation drive and directory into a file * Can copy up to 256 files per package * Can install multiple packages from a single source disk (or set of disks) * Checks for required available disk space before beginning installation * Can check that the user has inserted the correct disk in a multi-disk set * Prompts the user for confirmation before overwriting files * Displays "percentage complete" progress bar during installation Terms Used ========== The following terms are used throughout this User's Guide. Customer: The person who installs your package onto their system. Destination drive: The disk drive, selected by the customer, where the package will be copied during installation. Directory: Folder. Installation path: The drive and path, selected by the customer, where the package will be copied during installation. Package: The set of files (programs and data files) forming a single software product. Path: A chain of zero or more directories, possibly ending in a file name, which defines the location of a file or directory within a directory tree. Source disk: A disk containing the package to be installed. A term enclosed in angle brackets (e.g., ) is used as a place holder for another term (usually described in the surrounding text). The angle brackets are not part of the term. General Operation ================= To use Winstall, you create a set of one or more source disks containing your package. Next, you create an installation script file and copy it, along with WINSTALL.PRG, onto your source disk. You distribute your source disk(s) to your customer. The customer runs WINSTALL.PRG, which reads the installation script and performs the installation. Creating the Installation Script ================================ The installation script tells Winstall how to perform the installation. Installation script files have an "INS" extension. When it runs, Winstall looks for a file called WINSTALL.INS. If it finds the file, Winstall carries out the instructions it contains. If it cannot find WINSTALL.INS, Winstall presents a file-selection form and lets the customer select an INS file. This is described more fully in the "Multi-package Installation" section. You can create the INS file with an ASCII text editor. The file contains a series of lines. Each line represents a single command. The character in the first column of each line is the command code. If the command takes parameters, then exactly one space must separate the command code from the first parameter -- i.e., the first parameter starts in column 3. A sample INS file is shown below. # Installation script for Turbo Blaster n Turbo Blaster v 2.34 d TBLASTER s 1343254 f 1:\tblaster.prg %d\tblaster.prg f 1:\tax.jj %d\samples\tax.tb f 1:\tblaster.acc %b\tblaster.acc f 2:\templt1.tem %d\template\templt1.tem f 2:\templt2.tem %d\template\templt2.tem f 2:\tblaster.lib \lib\tblaster.lib a [1][Please see README.TXT |for release notes. ][OK] b [1][Don't forget to fill in |your registration card. ][OK] Following is a description of the Winstall commands. #: Comment Defines a comment line. The remaining text on the line is ignored by Winstall. There is no limit on the number of comment lines. Comment lines are optional. Example: # Installation script for Turbo Blaster a: After Message Defines the text for an alert that will appear at the end of (after) a successful installation. The parameter is a string suitable for the second parameter of form_alert(): * The first component, a number enclosed in square brackets, determines the type of icon displayed in the alert: [1]: Exclamation; [2]: Question; [3]: Stop. * The second component is a sequence of text lines surrounded by square brackets. Each line is separated by a "|" character. Up to five lines may be defined. Each line may contain up to 32 characters. The alert looks best if all lines are approximately the same length -- uses spaces to pad them. * The third component is a button label surrounded by square brackets. Only one "a" command may be defined per installation. The "a" command is optional. If it is omitted, no message will be displayed. Example: a [1][Please see README.TXT |for release notes. ][OK] b: Before Message Defines the text for an alert which will appear before installation begins. See the description of the "a" command for details. Example: b [1][Don't forget to fill in |your registration card. ][OK] c: Check Disk Ids Tells Winstall to check the id of each source disk after a disk swap. This feature is useful in multiple source-disk installations, where the customer is asked to swap disks several times. If this feature is enabled, Winstall will check for the existence of a special disk id file on the source disk to ensure that the customer inserted the correct one. The special disk id file is named .! (for example, 1.! or INSTALL.!). See the description of the "f" command for more information on disk ids. Only one "c" command may be defined. The "c" command is optional. If it is omitted, Winstall will not check disk ids. The "c" command takes no parameters. d: Default Destination Directory Defines the name of the default directory where you package will be installed. During installation, Winstall determines the default destination drive (A: unless the customer has a hard drive, in which case it is C:) and constructs the default installation path from the drive and directory. For example, if you define the default directory as TBLASTER and Winstall determines that the customer has a hard drive, Winstall will use C:\TBLASTER as the default installation path. Winstall allows the customer to edit the default installation path during installation. Only one "d" command may be defined. The "d" command is mandatory. Example: d TBLASTER f: Copy file Defines the name of a file that must be copied from a source disk to the destination path during installation. The "f" command uses the following syntax: f The component uses the following syntax: : is a string (maximum 8 characters; no spaces allowed) defining the source disk containing the file to copy. During installation, Winstall may prompt the customer to insert this disk in the source drive with a message like this: Please insert disk "" in drive A:. Leave the disk id blank if your package is distributed on one source disk. is the path -- directories and file name -- of the source file. Winstall uses this path to locate the source file on the source disk. The component uses one of the following formats: %d\ %b\ \ %d is a special token that is replaced with the installation path selected by the customer during installation. Use this form of the parameter to copy the file to the installation path. %b is a special token that is replaced with the drive name used to load desk accessories on the customer's system. Winstall replaces %b with A: if the user installs the package onto a floppy disk, or C: if the package is installed onto a hard disk. Use this form of the parameter to copy a desk accessory (.ACC file) to the root folder of the boot drive. If the parameter begins with a directory separator (\), Winstall will copy the file to the specified path on the installation drive. In all three forms of the component, is the path -- directories and file name -- of the destination file. Following are some example "f" commands. In the examples, the customer has selected D:\UTIL\TBLASTER as the installation path. f \tblaster.prg %d\tblaster.prg Copy TBLASTER.PRG from the root directory of the source disk to D:\UTIL\TBLASTER\TBLASTER.PRG. f \prgs\tblaster.prg %d\appl\tblaster.prg Copy TBLASTER.PRG from directory PRGS on the source disk to D:\UTIL\TBLASTER\APPL\TBLASTER.PRG. f 2-of-3:\pictures.dat %d\data\pictures.dat Copy PICTURES.DAT from the source disk labeled "2-of-3" to D:\UTIL\TBLASTER\DATA\PICTURES.DAT. f Install:\SAMPLES\TAX.JJ %d\samples\tax.tb Copy TAX.JJ from the SAMPLES directory on the source disk labeled "Install" to D:\UTIL\TBLASTER\SAMPLES\TAX.TB. f \tblaster.acc %b\tblaster.acc Copy TBLASTER.ACC from the root directory of the source disk to C:\TBLASTER.ACC. f \tblaster.lib \lib\tblaster.lib Copy TBLASTER.LIB from the source disk to D:\LIB\TBLASTER.LIB. Up to 256 "f" commands can be defined per INS file. n: Package Name Defines the name of the software package being installed. The package name may be up to 32 characters wide. The "n" command is mandatory. Only one "n" command may be defined. Example: n Turbo Blaster p: Patch Installation Path Patches the installation path selected by the customer into a specified file at a specified location. This command is useful if your package contains a desk accessory that must access disk files. Desk accessories have no fixed working directory; patching the installation path gives the desk accessory a place to locate its data files. Only one "p" command may be defined. The "p" command is optional. The syntax of the "p" command is: p uses the same syntax as the component of the "f" command. is the displacement in bytes from the start of the file where the installation path will be stored. You can determine the offset using PATCHIT.TTP, supplied with Winstall (see the "Using PatchIt" section for details). The offset is expressed in decimal. Example: p %b\tblaster.acc 64382 See the "Patching the Installation Path" section for further instructions on using this feature. s: Space Required Specifies the amount of disk space needed to install the package, in bytes. The size is expressed in decimal. Winstall uses the space value for two purposes: 1) To determine if the destination drive selected by the customer has enough space available to hold the package; 2) To update the progress bar displayed during installation. Only one "s" command may be defined. The "s" command is mandatory. Example: s 1328544 v: Version Defines the version identifier of the package being installed. The version identifier may be any text, up to 32 characters wide. The "v" command is optional. Only one "v" command may be defined. Example: v 1.23 Creating the Source Disks ========================= To create the source disk (or disks), copy the files in the package onto one or more diskettes. Leave enough room on the first disk for WINSTALL.PRG and WINSTALL.INS. If you need more than one disk, and want Winstall to verify that the user has inserted the correct disk during installation, create a disk id file on each disk. The disk id which appears in the disk id file name should match the sequence identifier printed on the disk's label. Example disk id file names: 1.! A.! I.! INSTALL.! 2.! B.! II.! SAMPLES.! 3.! C.! III.! FONTS.! Next, create a WINSTALL.INS file as described in the preceding section. The "f" commands should be listed in disk id order to prevent excess disk swapping. If you want Winstall to check disk ids during installation, don't forget to include a "c" command. Next, copy WINSTALL.PRG and WINSTALL.INS to your first disk. If you prefer, you can rename WINSTALL.PRG to INSTALL.PRG or some other name. However, don't rename WINSTALL.INS or Winstall won't be able to find it. Multi-package Installations =========================== You can use Winstall to install several packages from a single source disk (or set of disks). Similarly, you can use Winstall to install different configurations of the same package. By default, Winstall reads and interprets the installation commands in WINSTALL.INS. If this file is missing, Winstall displays a file-selector form and lets the customer select an INS file. For a multi-package installation, you can create one INS file per package -- e.g., TBLASTER.INS BLOB2.INS WRENCH.INS Each INS file contains the commands for installing one specific package. The customer selects the INS file associated with the package he or she wishes to install. Patching the Installation Path ============================== You must take certain steps before you can use Winstall's "p" command to patch the installation path into an executable file. In your program (or desk accessory), declare a character array at least 80 characters wide. Initialize the array with some text pattern that is very unlikely to occur elsewhere in your program, either intentionally or by accident. The array must be initialized with the text pattern during compilation or assembly, not at run time. The array must be in static memory -- it cannot be allocated on the stack. In C, you might declare the array like this: static char homePath[80 + 1] = "!!HOME_PATH!!"; After your program is compiled and linked, run PatchIt to locate the text pattern in the array (in the example above, you would look for !!HOME_PATH!!). See the "Using PatchIt" section for information on running the PatchIt program. Use the offset reported by PatchIt in Winstall's "p" command. When your program runs after installation, the homePath[] array will contain the installation path selected by the user. You can use this path to locate data files needed by your program or desk accessory. Using PatchIt ============= PatchIt (PATCHIT.TTP) is a utility program that helps you use Winstall's "p" (patch installation path) command. PatchIt can * Locate a string in a file and report the offset of the string from the start of the file * Patch (overwrite) a string into a file at a given location * Display the string in a file at a given location. PatchIt is a TTP program, so its parameters are provided via the command line. The space available for command-line parameters entered from the GEM desktop is limited, so you may want to run PatchIt from a command-line shell. To locate a string in a file and report the offset, use the following command: patchit -f PatchIt will display the position (byte offset) in decimal of the first occurrence of the string (if found). Example: patchit -f !!HOME_PATH!! tblaster.acc To patch a string into a file at a specified offset, use the following command: patchit -p -o Example: patchit -p D:\TBLASTER -o 61344 tblaster.acc To display a string at a given offset in a file, use the following command: patchit -d -o Example: patchit -d -o 61344 tblaster.acc