Installer Release Notes This document contains any changes to the Installer and its scripting language that were made after the release of version 1.0. This is a suppliment to the documentation found on the '91 DevCon disks. ---------------------------------------------------------------------------- Notes: The Installer now requires a 10000 byte stack. Please alter any Installer script icons so they have a stack size of 10000. Please remember that the string formating command ("..." ...) requires that interger values be formatted by "%ld", not "%d". All integer variables in the Installer are LONGWORDS. The documentation for "working" found in the DevCon notes is incorrect. The correct template is (working ...) where the strings will be concatinated to form a message which will appear below a standard line that reads "Working on Installation". The maximum size of a string in a script is 512 bytes. The maximum size of any string variable is 10000 bytes. If you need to create long help text you will need to break the text into 512 byte chunks and then use the automatic string concatination ability of the installer to create the final, larger string. Also, don't overlook the the use of line continuation of strings in scripts to make your scripts more managable. If you ever find that the installer reports a stack overflow error, look to see if it caused by too many small strings being concatinated and merge them into larger blocks. The "run" and "execute" statements only return the result of the command run or executed under 2.0; they always return 0 under 1.3. If you must have some result under both 1.3 and 2.0, try this combo: # in the DOS script to execute: failat 31 command if error setenv installer-result 10 else if warn setenv installer-result 5 else setenv installer-result 0 endif endif ; in the installer script (execute DOS-Script) (set theResult (getenv "installer-result")) When providing a pattern in a script, be sure it is less than 65 characters in length. Although patterns up to 128 characters in size may work, the maximum reliable length is 64. To convert an integer to a string, use the "cat" function. All integer arguments to "cat" are converted to strings during concatination. To convert a string to an integer do this: (set (+ )) One command that was previously left undocumented is the "debug" statement. Its template is (debug ...) When the Installer is run from a CLI, "debug" will print the values of the parameters with a space bewteen each parameter. For example, the statements (set myvar 2) (debug "This value of 'myvar' is" myvar) will print "This value of myvar is 2". If the parameter is an uninitialized variable, then debug will print "" as its value. ---------------------------------------------------------------------------- Changes for Installer v1.1 (10-1-91): Added a new variable "@execute-dir". If this variable is set to a valid path, then the installer will change directory to it whenever a "run" or "execute" statement is performed. ---------------------------------------------------------------------------- Changes for Installer v1.2 (10-4-91): Changed documentation for "working" statement to match reality. ---------------------------------------------------------------------------- Changes for Installer v1.4 (10-16-91): The "asknumber" now prints the allowed range below the integer gadget if the "range" parameter is given. Also, the user cannot proceed without entering a valid number. Fixed many UI and stack-related bugs. Installer no longer munges long lines found in the "user-startup" file. Fixed "exists" statement to match the documented return values. Added a new pattern matcher which more closely matches the functionality of the one found in the 2.0 dos.library. Added "user" statement which can be used to change the user level of the current installation. This statement should ONLY be used when debugging scripts. Remove such statements from any script before distribution of your product. The format is (user ) where is either 0 (NOVICE), 1 (AVERAGE) or 2 (EXPERT). This statement returns the current user level. ---------------------------------------------------------------------------- Changes for Installer v1.5 (10-17-91): Fixed "message" statement so its works correctly when help is provided. Fixed "run" and "execute" commands so that it does not abort incorrectly. Also, see the notes above for more information about the "run" and "execute". Fixed "working" so that it resets its text positioning. The LOGFILE tooltype can now accept a complete pathname, just not a file name. ---------------------------------------------------------------------------- Changes for Installer v1.6 (10-19-91): The Installer now handles negative numbers properly. Fixed pattern matching code so its doesn't overrun the stack. See note above about length of patterns. ---------------------------------------------------------------------------- Changes for Installer v1.7 (11-27-91): Added "shiftleft" and "shiftright" math operations. Their formats are (shiftleft ) (shiftrght ) Added "substr" statement to perform string operations. The format is (substr []) where start begins at 0 in the string. Count is optional -- if omitted then the remaining part of the string is returned. New, improved, "protect" command. The new format is (protect []) where protection values is a string giving changes to the file's protection bits. For example, "-d +a" would make a file undeletable and set to archived. As before, just giving a filename returns the current protection bits. Finally, the old version of "protect" still works. Which version is used is based on whether the second parameter is an integer (old method) or a string (new method). Fixed bugs in "tooltype" statement involving stack size and tooltypes. Fixed bug in "askfile" involving text in file name string gadget. Fixed bug in "askdir" involving the default drawer being on an unmounted volume. NOTE: It is always best to insure that the volume you want is mounted by using the "askdisk" command. That's one of the reasons why its provided. The predefined variables TRUE and FALSE now work right. The predefined variable "@copylib-help" now describes the user interface correctly. Fixed bug in "copyfiles" involving not cloning a file properly when inside a drawer that was just created. The "select" command in now a control statement. This means that "select" can be used as a case select construct. Only the selected element will be evaluated. The "getassign" command now works for variables instead of just literals. A busy pointer is displayed while the script is being compiled. ---------------------------------------------------------------------------- Changes for Installer v1.8 (12-15-91): Version 1.7 didn't work on 68000 systems. This one does. Added a SCRIPT tooltype that allows specification of the installer script to use. Fixed "getassign" so that it returns an empty string when no assignment exists instead of nil. Changed "askfile" do the default path can be either reference a file or a drawer. If a file, the filename gadget is filled in. Added a new parameter "swapcolors" to "tooltype". This instructs the installer to swap the first two planes of the image of the icon being modified if the version of the OS if less than 36 (version 1.3-). This does mean that your icons need have the 2.0 color scheme on your distribution disks. Added a new parameter "newpath" to "askdir" that allows for non-existant paths to be supplied as the default drawer. This is similar to the way that version 1.0 worked. The format is (askdir ... (newpath)) Added a new function "expandpath" that will take an any path and return the full path. For example, it might expand "SYS:c" to "System2.0:c". The format is (expandpath ) And finally, the installer now has user-defined procedures (subroutines). This functionality is very primative. There are no local variables. To define a new prodecure you use the "prodedure" command: (procedure ) You can then call the procedure thus: () Note that procedure-name is not a string, just a symbol name. ---------------------------------------------------------------------------- Changes for Installer v1.9 (12-15-91): Fixed "makedir" display. Fixed "copyfiles" so a choice of a directory works. If "infos" is specified for "copyfiles" and the destination drawer does not exist, a default icon will be made for the drawer the Installer creates. Changed "copylib" so it will create the destination directory as long as there is only one level missing. For example, copying to a non-existant "DEVS:midi" would create the directory "midi", but copying to "DEVS:midi/extra" where neither "midi" or "extra" exists would fail. This duplicates the functionality of "copyfiles". Fixed "procedure" so that it actually works! Added a new pre-defined variable "@app-name" which contains the APPNAME value given at startup. Added "noreq" parameter to "exists" so no requester is displayed if the path given is not on a mounted volume. In this case the result is 0 (doesn't exist). The format is: (exists (noreq)) Added "resident" parameter to "getversion". You can now get the version of a library or device in memory. For example: (getversion "intuition.library" (resident)) would return the version/revision of intuition. Note that using the "resident" parameter causes first the library and then the device list to be checked. Added option to "exit" to print extra explanatory text in the final window. The format is (exit ...) Added a new function "database", which can return information about the Amiga that the Installer is running on. The format is (database ) where "feature" is a string. This function always returns a string result, even if the result looks like a number. The feature given is unknown, the function returns "unknown". The currently understood features and their possible values are: "vblank": "50", "60" "cpu": "68000", "68010", "68020", "68030", "68040" And now for the big one: The initial user options displays are now a command! The format is (welcome ...) Old scripts will still work, as the Installer can detect that you never referenced "welcome" during compilation. This means that you can execute code before the first displays come up. You can even abort if you find conditions unbearable. Note that the state of the "@user-level" and "@pretend" variables will be based on the initial defaults including any modification by tooltypes. The string arguments are prepended to the standard help text for whichever of the two initial displays appears first. ---------------------------------------------------------------------------- Changes for Installer v1.10 (12-30-91): Fixed bug in "copyfiles" (although I would like others to test this). The bug was that sometimes doing a confirmed copyfiles followed by an unconfirmed copyfiles would cause a crash on the next user interface item. Fixed bug in the code that makes an assign under 1.3. ("I hate, I hate, I hate DOS 1.3!") Added a debugging parameter to "askdisk". If you add "(assigns)" as a parameter, then assigns will match the askdisk request also. Note that this parameter should be removed before putting the install script on your distribution disk! Expanded the parameter "optional" when used with "copyfile" or "copylib", also added it to "delete". The new format is (optional