home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 8 / FreshFishVol8-CD2.bin / bbs / util / installer-1.26.lha / Installer / Installer.lha / Installer1.24 / Installer.doc < prev    next >
Text File  |  1993-03-26  |  64KB  |  1,851 lines
  1.  
  2.         Installer.doc
  3.             Documentation for 1.24 Installer 
  4.             Last Revised: January 12th, 1993
  5.  
  6.  
  7. (C) Copyright 1991-93 Commodore-Amiga,Inc.  All Rights Resrved
  8.  
  9.  
  10. Contents:
  11.  
  12.     1 Background
  13.  
  14.     2 Overview
  15.       2.1  Standard Invocation
  16.       2.2  Initial Actions
  17.       2.3  Startup Screens
  18.       2.4  Installation Actions
  19.  
  20.     3 Scripting Language Tutorial
  21.       3.1  Basic Elements
  22.       3.2  Escape Characters
  23.       3.3  Symbols (Variables)
  24.       3.4  Types of Symbols
  25.       3.5  Statements
  26.       3.6  Data Types
  27.       3.7  Special Features
  28.       3.8  Miscellaneous
  29.  
  30.     4 Installer Language Reference
  31.       4.1  Notes
  32.       4.2  Statements
  33.       4.3  Control Statements
  34.       4.4  Debugging Statements
  35.       4.5  User-Defined Procedures
  36.       4.6  Functions
  37.       4.7  Summary of Parameters
  38.       4.8  Pre-Defined Variables
  39.  
  40.     5 Installer Language Quick Reference
  41.       5.1  Overview
  42.       5.2  Quick Language Overview
  43.       5.3  Pre-Defined Variables
  44.       5.4  Default Help String Variables
  45.       5.5  Statements
  46.       5.6  Functions
  47.  
  48.  
  49.                 Section 1: Background
  50.  
  51. Installation of applications from floppy disks onto a hard disk has proven to be
  52. a very inconsistent and often frustrating endeavor for most end-users.  This has
  53. been caused by many factors, some of which are:
  54.  
  55.     a. Many products do not come with any utility or script to install an
  56.        application on a hard disk.
  57.  
  58.     b. Many products assume a great deal of familiarity with the startup process
  59.        of the Amiga and applications, including assigns, device names (as
  60.        opposed to volume names), etc.
  61.  
  62.     c. The installation scripts or utilities included with some products vary
  63.        widely in their ability to deal with different environments and systems.
  64.  
  65. About a year ago, Commodore set out to remedy this situation, by developing a
  66. standard tool that developers can include with their products, which provides
  67. the user with a standard way to install applications.  The Installer's features
  68. were based on a number of assumptions:
  69.  
  70.     a. Installation requirements vary widely---some need assigns, some need new
  71.        drawers created, some install pieces in system drawers such as a fonts
  72.        drawer, a `product' might be just an upgrade and the installation must
  73.        check to see which version (if any) they currently have installed, etc.
  74.  
  75.     b. Different users have different levels of comfort and expertise when
  76.        attempting to install software, and the Installer should be able to
  77.        accommodate a range of users.  Many installation scripts assume a great
  78.        deal of knowledge, which is very intimidating for a novice.
  79.  
  80.     c. The installer tool must be very flexible internally, but present a
  81.        consistent pleasant graphical user interface to the user that only shows
  82.        the user information or prompts that they need to see.  The Installer
  83.        should be resolution, color and font sensitive.
  84.  
  85.     d. Writing scripts to install an application will require some effort, but
  86.        certainly no more than writing an AmigaDOS shell script equivalent, and
  87.        the resulting installation procedure will be more friendly, flexible, and
  88.        much better looking than the latter.
  89.  
  90.     e. Not everyone will be running 2.0 by the time the tool becomes available,
  91.        so it must run under 1.3 and 2.0.
  92.  
  93.  
  94.                 Section 2: Overview
  95.  
  96. The Installer is a script driven program, that presents a consistent
  97. installation environment to the end user.  The user never sees the script.
  98. Instead they are presented with simple yes/no choices, and may be asked to
  99. specify locations to put things on their system.
  100.  
  101. To accommodate different user levels, they can choose to run the tool in novice,
  102. average or expert modes.  Scripts can include help text to explain any choices
  103. that the user must make.  At each step the user is given the option of aborting
  104. the installation.
  105.  
  106.  
  107.  
  108.  
  109. 2.1  Standard Invocation
  110.  
  111. The Installer program requires a 10000 byte stack.  Project icons for Installer
  112. script should indicate a stack size of 10000.  If starting Installer from a CLI,
  113. first do a "Stack 10000".
  114.  
  115. The Installer is normally started up from a Workbench Project icon which has the
  116. same name as the script to interpret and has a default tool of Installer.
  117. A number of tooltypes are available to modify the operation of the Installer:
  118.  
  119.     SCRIPT - Path to a script file to be used with Installer.
  120.  
  121.     APPNAME - Name of the application being installed (appears in the startup
  122.               screen).  This MUST be given.
  123.  
  124.     MINUSER - The minimum possible operation mode of the installation for a
  125.               script.  This will be either NOVICE (all decisions made by
  126.               Installer), AVERAGE (only important decisions made by user) or
  127.               EXPERT (user confirms almost all actions).  The Default is NOVICE.
  128.  
  129.     DEFUSER - Indicates which operation mode button should be initially
  130.               selected.  Same values as MINUSER, with the value of the MINUSER
  131.               tooltype being the default (which will be NOVICE if MINUSER not
  132.               defined).
  133.  
  134.     NOPRINT - If set to FALSE, then the printer option in the  log file settings
  135.               will be ghosted.
  136.  
  137.     PRETEND - If set to FALSE, indicates that PRETEND mode not available for
  138.               this script.
  139.  
  140.     LANGUAGE - Used to set the variable @language (default for @language is
  141.                "english".  The use of this variable is left up to the install
  142.                script.
  143.  
  144.     LOGFILE - The name of the log file that the Installer should use.  This must
  145.               be a full path.  The default is "install_log_file".
  146.  
  147.     LOG - In NOVICE mode the default is to create a log file (to disk).  If this
  148.           tooltype is set to FALSE, the creation of a log file in NOVICE mode is
  149.           disabled.
  150.  
  151. Although the installer can be started up from the CLI, that is not the
  152. recommended mode.  CLI invocation is provided mainly for script debugging
  153. purposes.  The command template is:
  154.  
  155. SCRIPT/k,APPNAME,MINUSER,DEFUSER,LOGFILE,NOLOG/s,NOPRETEND/s,
  156. NOPRINT/s,LANGUAGE/k
  157.  
  158.  
  159.  
  160.  
  161. 2.2  Initial Actions
  162.  
  163. The first thing the installer does is compile the installation script into an
  164. internal format that can be easily interpreted.  If there are syntax errors in
  165. the script, they will be caught during this phase.
  166.  
  167.  
  168.  
  169.  
  170. 2.3  Startup Screens
  171.  
  172. Next, the Installer asks the user what Installation Mode to run in, either
  173. NOVICE, AVERAGE or EXPERT.  If the user chooses NOVICE, they will not be asked
  174. any more questions (although they may be requested to do things).  In the other
  175. user levels, a second display appears asking the user if he wants to install
  176. "for real" or "do a dry run", and if he wants a transcription of the
  177. installation process written to either a file or printer.
  178.  
  179.  
  180.  
  181.  
  182. 2.4  Installation Actions
  183.  
  184. Now the Installer interprets its internal version of the script.  Any commands
  185. that call for a user interface will cause the Installer to algorithmically
  186. generate a display, always including buttons to allow for context sensitive help
  187. and aborting the installation. 
  188.  
  189.  
  190.             Section 3: Scripting Language Tutorial
  191.  
  192. The script language of the Installer is based on LISP.  It is not difficult to
  193. learn, but requires a lot of parentheses.  An Installer script can easily be
  194. made to look very readable.
  195.  
  196.  
  197.  
  198.  
  199. 3.1  Basic Elements
  200.  
  201. The basic elements of the installer language are:
  202.  
  203.     Type                  Example
  204.     ----                  -------
  205.     decimal integers      5
  206.     hexadecimal integers  $a000
  207.     binary integers       %0010010
  208.     strings               "Hello" or 'Hello'
  209.     symbols               x
  210.     comments              ; this is a comment
  211.     ( )                   for statement definition
  212.     space                 delimits symbols
  213.      (or any white space)
  214.  
  215.  
  216.  
  217.  
  218. 3.2  Escape Characters
  219.  
  220. Escape characters are supported as in the C language:
  221.  
  222.     Escape
  223.     sequence  Produces
  224.     --------  --------
  225.     '\n'      newline character
  226.     '\r'      return character
  227.     '\t'      tab character
  228.     '\0'      a NUL character
  229.     '\"'      a double-quote
  230.     '\\'      a backslash
  231.  
  232.  
  233.  
  234.  
  235. 3.3  Symbols (Variables)
  236.  
  237. A symbol is any seq