
The _launcherr.ss_ library in the "launcher" collection imports
mzlib:file^, dynext:compile^, and dynext:link^, and exports the
following procedures for creating MzScheme and MrEd launcher
executables.

===== Launcher creation ========================================

> (make-mred-launcher args dest [aux]) - Creates the launcher
   `dest'. The `dest' executable (for the current OS platform) will
   start MrEd with the command-line arguments specified as strings in
   the list `args'. Extra arguments passed to the launcher at run-time
   will be appended (modulo special X flag handling, as described
   below) to this list and passed on to MrEd. If `dest' exists
   already (as a file or directory), it is replaced.

   `make-mred-launcher' transforms `args' as necessary to avoid
   mutations caused by passing the strings through the
   platform-specific launching mechanism (e.g, as /bin/sh arguments),
   so the strings in `flags' arrive to MrEd intact.

   The optional `aux' argument is an association list for
   platform-specific options (i.e., it is a list of pairs where the
   first element of the pair is a key symbol and the second element is
   the value for that key). The currently supported keys are as
   follows:

      _'icns_ (Mac OS X) - an icon file path (suffix ".icns") to
              use for the executable's desktop icon

      _'ico_ (Windows) - an icon file path (suffix ".ico") to
              use for the executable's desktop icon; the executable
              will have 16x16, 32x32, and 48x48 icons at 4-bit,
              8-bit, and 32-bit (RBBA) depths; the icons are
              copied and generated from any 16x16, 32x32, and 48x48
              icons in the ".ico" file
 
      _'independent?_  (Windows) - a boolean; #t creates an old-style
              launcher that is independent of the MzScheme or MrEd
              binary, like "Setup PLT.exe"

      -'exe-name_ (Mac OS X, MrEd 'script[-3m] variant) - provides the
              base name for a 'normal variant launcher, which the
              script will call ignoring `args'; if this name is not
              provided, the script will go through the MrEd executable

      _'creator_ (Mac OS X) - provides a 4-character string to use as
              the application signature.

      _'file-types_ (Mac OS X) - provides a list of association lists,
              one for each type of file handled by the application;
              each association is a 2-element list, where the first (key)
              element is a string recognized by Finder, and the second
              element is a plist value (see doc.tx in the "xml" collection);
              see plt/collects/drscheme/drscheme.filetypes for an example.

      -'resource-files_ (Mac OS X) - extra files to copy into the
              "Resources" directory of the generated executable

      _'forget-exe?_ (Windows, Mac OS X) - a boolean; #t does not 
              preserve the original executable name for
              `(find-system-path 'exec-file)'; the main consequence is
              that library collections will be found relative to the
              launcher instead of the original executable

   See also `build-aux-from-path' below. The default `aux' is `null'.

   For Unix/X, the script created by `make-mred-launcher' detects and
   handles X flags specially when they appear as the initial arguments
   to the script. Instead of appending these arguments to the end of
   `args', they are spliced in after any X Windows flags already
   listed listed in `args'. The remaining arguments (i.e., all script
   flags and arguments after the last X Windows flag or argument) are
   then appended after the spliced `args'.

   For Mac OS Classic, the creation of launchers requires the
   (one-time) use of an extension, starter-setup.so.  This extension
   is distributed with DrScheme bundles, and can also be built
   automatically from the source if necessary (and if the user has a
   copy of Codewarrior 5).  The creation of launchers on 68k platforms
   is significantly more fragile than on PPC platforms.  In
   particular, any launcher created on a 68k platform (or using a 68k
   binary) must be invoked at least once while that launcher is in the
   same folder as the MrEd copy it is to be linked to. Note also that
   once created, these launchers are bound in a truly tenacious way to
   MrEd; short of deleting MrEd entirely, it's nearly impossible to
   disconnect them.
   
> (make-mzscheme-launcher args dest [aux]) - Same as
   `make-mred-launcher', but for starting MzScheme. (No special Unix/X
   handling.)


> (make-mred-program-launcher file collection dest) - Calls
   `make-mred-launcher' with arguments that start the MrEd program
   implemented by `collection': (list "-mvL-" file collection).
   The aux argument is generated by stripping the suffix from `file',
   adding it to the path of `collection', and passing the result to
   `build-aux-from-path'.

> (make-mzscheme-program-launcher file collection dest) - Calls
   `make-mzscheme-launcher' with arguments that start the MzScheme
   program implemented by `file' in `collection': (list "-mvL-" file
   collection). The aux argument is generated by stripping the suffix
   from `file', adding it to the path of `collection', and passing the
   result to `build-aux-from-path'.


> (install-mred-program-launcher file collection name) - Calls
   `make-mred-launcher' with the destintation returned by
   (mred-program-launcher-path name); the `file' and `collection'
   arguments are passed on to `make-mred-launcher'.

> (install-mzscheme-program-launcher file collection name) - Calls
   `make-mzscheme-launcher' with the destintation returned by
   (mzscheme-program-launcher-path name); the `file' and `collection'
   arguments are passed on to `make-mzscheme-launcher'.

===== Launcher paths and platform conventions ============================

> (mred-program-launcher-path name) returns a pathname for an executable
   in the current PLT home directory called `name'.  For Windows, the
   ".exe" suffix is automatically appended to `name'. For Unix, `name'
   is changed to lowercase, whitespace is changed to `-', and the path
   includes the bin subdirectory of the PLT home directory. For Mac OS
   X, the ".app" suffix is appened to `name'.

> (mzscheme-program-launcher-path name) returns the same pathname as
   (mred-program-launcher-path name) for Unix, Windows, and Mac OS Classic.
   For Mac OS X, the result is the same as for Unix.


> (mred-launcher-is-directory?) - Returns #t if MrEd launchers for the
  current platform correspond to directories (as on Mac OS X).

> (mzscheme-launcher-is-directory?) - Returns #t if MzScheme launchers
  for the current platform correspond to directories.


> (mred-launcher-put-file-extension+style+filters) - Returns three
  values suitable for use as the `extension', `style', and `filters'
  arguments to `put-file', respectively. If MrEd launchers for this
  platform are directories, the `style' result is suitable for use
  with `get-directory', and the `extension' result may be a string
  indicating a required extension for the directory name (e.g., ".app"
  for Mac OS X).

> (mzscheme-launcher-put-file-extension+style+filters) - Like
  `mred-launcher-get-file-extension+style+filters', but for MzScheme
  launchers.

===== Miscellaneous ========================================

> (mred-launcher-up-to-date? dest [aux]) - Returns #t if the
    launcher `dest' does not need to be updated, assuming
    that `dest' is a launcher and its arguments have not changed.

> (mzscheme-launcher-up-to-date? dest [aux]) - Analogous to
    `mred-launcher-up-to-date?'.


> (build-aux-from-path path) - Creates an `aux' association list
    by a suffix to the path, such as ".icns", and checking whether
    such a file exists. The recognized suffixes are as follows:

       * .icns => 'icns file
       * .ico  => 'ico file
       * .lch  => 'independent? as #t (file content is ignored)
       * .creator => 'creator as initial 4-characters in the file
       * .filetypes => 'file-types as read content (a single S-expr),
                       and 'resource-files as a list constructed by
                       finding "CFBundleTypeIconFile" entries in
                       'file-types

> (current-launcher-variant [symbol]) - Gets or sets a symbol
   parameter that indicates a variant of MzScheme or MrEd to use for
   launcher creation and for generating launcher names. The 'normal
   variant is usually available. For Unix platforms, the only other
   possibility is '3m. For Mac OS X, the '3m variant is available, and
   the 'script and 'script-3m variants are available for MrEd.

> (available-mred-variants) - Returns a list of symbols
  corresponding to available variants of MrEd.

> (available-mzscheme-variants) - Returns a list of symbols
  corresponding to available variants of MrEd.
