
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). See `create-embedding-executable' (from the
   "compiler" collection) for a list that applies to Windows launchers
   and Mac OS X MrEd launchers; the following additional associations
   apply to launchers:

      _'independent?_ (Windows) - a boolean; #t creates an old-style
              launcher that is independent of the MzScheme or MrEd
              binary, like "Setup PLT.exe"; no other `aux'
              associations are used for an old-style launcher

      -'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

      _'relative?_ (all) - a boolean, where #t means that the generate
              shell script should launch the executable through a
              relative path

   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 destination 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 destination 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 appended 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 are directories from the user's perspective.

> (mzscheme-launcher-is-directory?) - Returns #t if MzScheme launchers
  for the current platform are directories from the user's perspective.


> (mred-launcher-is-actually-directory?) - Returns #t if MrEd
  launchers for the current platform are implemented as directories.

> (mzscheme-launcher-is-actually-directory?) - Returns #t if MzScheme
  launchers for the current platform are implemented as directories.


> (mred-launcher-add-suffix path) - Returns a path with a suitable
  executable suffix added, if it's not present already.

> (mzscheme-launcher-add-suffix path) - Like
  `mred-launcher-add-suffix', but for MzScheme launchers.


> (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 from the user perspective, 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.
