393 lines
14 KiB
Racket
393 lines
14 KiB
Racket
#lang scribble/doc
|
|
@(require scribble/manual
|
|
"common.ss"
|
|
(for-label racket/base
|
|
racket/unit
|
|
racket/contract
|
|
launcher/launcher
|
|
launcher/launcher-sig
|
|
launcher/launcher-unit
|
|
compiler/embed
|
|
racket/gui/base))
|
|
|
|
@title[#:tag "launcher"]{Installation-Specific Launchers}
|
|
|
|
@defmodule[launcher/launcher]
|
|
|
|
The @racketmodname[launcher/launcher] library provides functions for
|
|
creating @defterm{launchers}, which are similar to stand-alone
|
|
executables, but sometimes smaller because they depend permanently on
|
|
the local Racket installation. In the case of Unix, in particular,
|
|
a launcher is simply a shell script. The @exec{raco exe} command provides no
|
|
direct support for creating launchers.
|
|
|
|
@section{Creating Launchers}
|
|
|
|
@defproc[(make-gracket-launcher [args (listof string?)]
|
|
[dest path-string?]
|
|
[aux (listof (cons/c symbol? any/c)) null])
|
|
void?]{
|
|
|
|
Creates the launcher @racket[dest], which starts GRacket with the
|
|
command-line arguments specified as strings in @racket[args]. Extra
|
|
arguments passed to the launcher at run-time are appended (modulo
|
|
special Unix/X flag handling, as described below) to this list and
|
|
passed on to GRacket. If @racket[dest] exists already, as either a file
|
|
or directory, it is replaced.
|
|
|
|
The optional @racket[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 also @racket[build-aux-from-path]. See
|
|
@racket[create-embedding-executable] for a list that applies to both
|
|
stand-alone executables and launchers under Windows and Mac OS X GRacket;
|
|
the following additional associations apply to launchers:
|
|
|
|
@itemize[
|
|
|
|
@item{@racket['independent?] (Windows) --- a boolean; @racket[#t]
|
|
creates an old-style launcher that is independent of the
|
|
MzRacket or GRacket binary, like @exec{setup-plt.exe}. No other
|
|
@racket[aux] associations are used for an old-style launcher.}
|
|
|
|
@item{@racket['exe-name] (Mac OS X, @racket['script-3m] or
|
|
@racket['script-cgc] variant) --- provides the base name for a
|
|
@racket['3m]-/@racket['cgc]-variant launcher, which the script
|
|
will call ignoring @racket[args]. If this name is not provided,
|
|
the script will go through the GRacket executable as usual.}
|
|
|
|
@item{@racket['relative?] (all platforms) --- a boolean, where
|
|
@racket[#t] means that the generated launcher should find the
|
|
base GRacket executable through a relative path.}
|
|
|
|
]
|
|
|
|
For Unix/X, the script created by @racket[make-mred-launcher] detects
|
|
and handles X Windows flags specially when they appear as the initial
|
|
arguments to the script. Instead of appending these arguments to the
|
|
end of @racket[args], they are spliced in after any X Windows flags
|
|
already listed listed in @racket[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 @racket[args].}
|
|
|
|
|
|
@defproc[(make-racket-launcher [args (listof string?)]
|
|
[dest path-string?]
|
|
[aux (listof (cons/c symbol? any/c)) null])
|
|
void?]{
|
|
|
|
Like @racket[make-gracket-launcher], but for starting Racket. Under Mac
|
|
OS X, the @racket['exe-name] @racket[aux] association is ignored.}
|
|
|
|
|
|
@defproc[(make-gracket-program-launcher [file string?]
|
|
[collection string?]
|
|
[dest path-string?])
|
|
void?]{
|
|
|
|
Calls @racket[make-gracket-launcher] with arguments that start the
|
|
GRacket program implemented by @racket[file] in @racket[collection]:
|
|
@racket[(list "-l-" (string-append collection "/" file))]. The
|
|
@racket[_aux] argument to @racket[make-gracket-launcher] is generated
|
|
by stripping the suffix (if any) from @racket[file], adding it to the
|
|
path of @racket[collection], and passing the result to
|
|
@racket[build-aux-from-path].}
|
|
|
|
|
|
@defproc[(make-racket-program-launcher [file string?]
|
|
[collection string?]
|
|
[dest path-string?])
|
|
void?]{
|
|
|
|
Like @racket[make-gracket-program-launcher], but for
|
|
@racket[make-racket-launcher].}
|
|
|
|
|
|
@defproc[(install-gracket-program-launcher [file string?]
|
|
[collection string?]
|
|
[name string?])
|
|
void?]{
|
|
|
|
Same as
|
|
|
|
@racketblock[
|
|
(make-gracket-program-launcher
|
|
file collection
|
|
(gracket-program-launcher-path name))
|
|
]}
|
|
|
|
@defproc[(install-racket-program-launcher [file string?]
|
|
[collection string?]
|
|
[name string?])
|
|
void?]{
|
|
|
|
Same as
|
|
|
|
@racketblock[
|
|
(make-racket-program-launcher
|
|
file collection
|
|
(racket-program-launcher-path name))
|
|
]}
|
|
|
|
|
|
@deftogether[(
|
|
@defproc[(make-mred-launcher [args (listof string?)]
|
|
[dest path-string?]
|
|
[aux (listof (cons/c symbol? any/c)) null])
|
|
void?]
|
|
@defproc[(make-mred-program-launcher [file string?]
|
|
[collection string?]
|
|
[dest path-string?])
|
|
void?]
|
|
@defproc[(install-mred-program-launcher [file string?]
|
|
[collection string?]
|
|
[name string?])
|
|
void?]
|
|
)]{
|
|
|
|
Backward-compatible version of @racket[make-gracket-launcher], etc.,
|
|
that adds @racket["-I" "scheme/gui/init"] to the start of the
|
|
command-line arguments.}
|
|
|
|
@deftogether[(
|
|
@defproc[(make-mzscheme-launcher [args (listof string?)]
|
|
[dest path-string?]
|
|
[aux (listof (cons/c symbol? any/c)) null])
|
|
void?]
|
|
@defproc[(make-mzscheme-program-launcher [file string?]
|
|
[collection string?]
|
|
[dest path-string?])
|
|
void?]
|
|
@defproc[(install-mzscheme-program-launcher [file string?]
|
|
[collection string?]
|
|
[name string?])
|
|
void?]
|
|
)]{
|
|
|
|
Backward-compatible version of @racket[make-racket-launcher], etc.,
|
|
that adds @racket["-I" "scheme/init"] to the start of the command-line
|
|
arguments.}
|
|
|
|
@; ----------------------------------------------------------------------
|
|
|
|
@section{Launcher Path and Platform Conventions}
|
|
|
|
@defproc[(gracket-program-launcher-path [name string?]) path?]{
|
|
|
|
Returns a pathname for an executable in the Racket installation
|
|
called something like @racket[name]. For Windows, the @filepath{.exe}
|
|
suffix is automatically appended to @racket[name]. For Unix,
|
|
@racket[name] is changed to lowercase, whitespace is changed to
|
|
@litchar{-}, and the path includes the @filepath{bin} subdirectory of
|
|
the Racket installation. For Mac OS X, the @filepath{.app} suffix
|
|
is appended to @racket[name].}
|
|
|
|
|
|
@defproc[(racket-program-launcher-path [name string?]) path?]{
|
|
|
|
Returns the same path as @racket[(gracket-program-launcher-path name)]
|
|
for Unix and Windows. For Mac OS X, the result is the same as for
|
|
Unix.}
|
|
|
|
|
|
@defproc[(gracket-launcher-is-directory?) boolean?]{
|
|
|
|
Returns @racket[#t] if GRacket launchers for the current platform are
|
|
directories from the user's perspective. For all currently supported
|
|
platforms, the result is @racket[#f].}
|
|
|
|
|
|
@defproc[(racket-launcher-is-directory?) boolean?]{
|
|
|
|
Like @racket[gracket-launcher-is-directory?], but for Racket
|
|
launchers.}
|
|
|
|
|
|
@defproc[(gracket-launcher-is-actually-directory?) boolean?]{
|
|
|
|
Returns @racket[#t] if GRacket launchers for the current platform are
|
|
implemented as directories from the filesystem's perspective. The
|
|
result is @racket[#t] for Mac OS X, @racket[#f] for all other
|
|
platforms.}
|
|
|
|
|
|
@defproc[(racket-launcher-is-actually-directory?) boolean?]{
|
|
|
|
Like @racket[gracket-launcher-is-actuall-directory?], but for Racket
|
|
launchers. The result is @racket[#f] for all platforms.}
|
|
|
|
|
|
@defproc[(gracket-launcher-add-suffix [path-string? path]) path?]{
|
|
|
|
Returns a path with a suitable executable suffix added, if it's not
|
|
present already.}
|
|
|
|
@defproc[(racket-launcher-add-suffix [path-string? path]) path?]{
|
|
|
|
Like @racket[gracket-launcher-add-suffix], but for Racket launchers.}
|
|
|
|
|
|
@defproc[(gracket-launcher-put-file-extension+style+filters)
|
|
(values (or/c string? false/c)
|
|
(listof (one-of/c 'packages 'enter-packages))
|
|
(listof (list/c string? string?)))]{
|
|
|
|
Returns three values suitable for use as the @racket[extension],
|
|
@racket[style], and @racket[filters] arguments to @racket[put-file],
|
|
respectively.
|
|
|
|
If GRacket launchers for the current platform were directories form the
|
|
user's perspective, the @racket[style] result is suitable for use with
|
|
@racket[get-directory], and the @racket[extension] result may be a
|
|
string indicating a required extension for the directory name. }
|
|
|
|
|
|
@defproc[(racket-launcher-put-file-extension+style+filters)
|
|
(values (or/c string? false/c)
|
|
(listof (one-of/c 'packages 'enter-packages))
|
|
(listof (list/c string? string?)))]{
|
|
|
|
Like @racket[gracket-launcher-get-file-extension+style+filters], but for
|
|
Racket launchers.}
|
|
|
|
@deftogether[(
|
|
@defproc[(mred-program-launcher-path [name string?]) path?]
|
|
@defproc[(mred-launcher-is-directory?) boolean?]
|
|
@defproc[(mred-launcher-is-actually-directory?) boolean?]
|
|
@defproc[(mred-launcher-add-suffix [path-string? path]) path?]
|
|
@defproc[(mred-launcher-put-file-extension+style+filters)
|
|
(values (or/c string? false/c)
|
|
(listof (one-of/c 'packages 'enter-packages))
|
|
(listof (list/c string? string?)))]
|
|
)]{
|
|
|
|
Backward-compatible aliases for
|
|
@racket[gracket-program-launcher-path], etc.}
|
|
|
|
@deftogether[(
|
|
@defproc[(mzscheme-program-launcher-path [name string?]) path?]
|
|
@defproc[(mzscheme-launcher-is-directory?) boolean?]
|
|
@defproc[(mzscheme-launcher-is-actually-directory?) boolean?]
|
|
@defproc[(mzscheme-launcher-add-suffix [path-string? path]) path?]
|
|
@defproc[(mzscheme-launcher-put-file-extension+style+filters)
|
|
(values (or/c string? false/c)
|
|
(listof (one-of/c 'packages 'enter-packages))
|
|
(listof (list/c string? string?)))]
|
|
)]{
|
|
|
|
Backward-compatible aliases for
|
|
@racket[racket-program-launcher-path], etc.}
|
|
|
|
@; ----------------------------------------------------------------------
|
|
|
|
@section{Launcher Configuration}
|
|
|
|
@defproc[(gracket-launcher-up-to-date? [dest path-string?]
|
|
[aux (listof (cons/c symbol? any/c))])
|
|
boolean?]{
|
|
|
|
Returns @racket[#t] if the GRacket launcher @racket[dest] does not need
|
|
to be updated, assuming that @racket[dest] is a launcher and its
|
|
arguments have not changed.}
|
|
|
|
@defproc[(racket-launcher-up-to-date? [dest path-string?]
|
|
[aux (listof (cons/c symbol? any/c))])
|
|
boolean?]{
|
|
|
|
Analogous to @racket[gracket-launcher-up-to-date?], but for a Racket
|
|
launcher.}
|
|
|
|
@defproc[(build-aux-from-path [path path-string?])
|
|
(listof (cons/c symbol? any/c))]{
|
|
|
|
Creates an association list suitable for use with
|
|
@racket[make-gracket-launcher] or @racket[create-embedding-executable].
|
|
It builds associations by adding to @racket[path] suffixes, such as
|
|
@filepath{.icns}, and checking whether such a file exists.
|
|
|
|
The recognized suffixes are as follows:
|
|
|
|
@itemize[
|
|
|
|
@item{@filepath{.icns} @'rarr @racket['icns] file for use under Mac
|
|
OS X}
|
|
|
|
@item{@filepath{.ico} @'rarr @racket['ico] file for use under
|
|
Windows}
|
|
|
|
@item{@filepath{.lch} @'rarr @racket['independent?] as @racket[#t]
|
|
(the file content is ignored) for use under Windows}
|
|
|
|
@item{@filepath{.creator} @'rarr @racket['creator] as the initial
|
|
four characters in the file for use under Mac OS X}
|
|
|
|
@item{@filepath{.filetypes} @'rarr @racket['file-types] as
|
|
@racket[read] content (a single S-expression), and
|
|
@racket['resource-files] as a list constructed by finding
|
|
@racket["CFBundleTypeIconFile"] entries in @racket['file-types]
|
|
(and filtering duplicates); for use under Mac OS X}
|
|
|
|
@item{@filepath{.utiexports} @'rarr @racket['uti-exports] as
|
|
@racket[read] content (a single S-expression); for use under
|
|
Mac OS X}
|
|
|
|
]}
|
|
|
|
@defparam[current-launcher-variant variant symbol?]{
|
|
|
|
A parameter that indicates a variant of Racket or GRacket to use for
|
|
launcher creation and for generating launcher names. The default is
|
|
the result of @racket[(system-type 'gc)]. Under Unix and Windows, the
|
|
possibilities are @racket['cgc] and @racket['3m]. Under Mac OS X, the
|
|
@racket['script-3m] and @racket['script-cgc] variants are also
|
|
available for GRacket launchers.}
|
|
|
|
@defproc[(available-gracket-variants) (listof symbol?)]{
|
|
|
|
Returns a list of symbols corresponding to available variants of GRacket
|
|
in the current Racket installation. The list normally includes at
|
|
least one of @racket['3m] or @racket['cgc]--- whichever is the result
|
|
of @racket[(system-type 'gc)]---and may include the other, as well as
|
|
@racket['script-3m] and/or @racket['script-cgc] under Mac OS X.}
|
|
|
|
@defproc[(available-racket-variants) (listof symbol?)]{
|
|
|
|
Returns a list of symbols corresponding to available variants of
|
|
Racket in the current Racket installation. The list normally
|
|
includes at least one of @racket['3m] or @racket['cgc]---whichever is
|
|
the result of @racket[(system-type 'gc)]---and may include the other.}
|
|
|
|
@deftogether[(
|
|
@defproc[(mred-launcher-up-to-date? [dest path-string?]
|
|
[aux (listof (cons/c symbol? any/c))])
|
|
boolean?]
|
|
@defproc[(mzscheme-launcher-up-to-date? [dest path-string?]
|
|
[aux (listof (cons/c symbol? any/c))])
|
|
boolean?]
|
|
@defproc[(available-mred-variants) (listof symbol?)]
|
|
@defproc[(available-mzscheme-variants) (listof symbol?)]
|
|
)]{
|
|
Backward-compatible aliases for
|
|
@racket[gracket-launcher-up-to-date?], etc.}
|
|
|
|
|
|
@; ----------------------------------------
|
|
|
|
@section{Launcher Creation Signature}
|
|
|
|
@defmodule[launcher/launcher-sig]
|
|
|
|
@defsignature/splice[launcher^ ()]{
|
|
|
|
Includes the identifiers provided by @racketmodname[launcher/launcher].}
|
|
|
|
@; ----------------------------------------
|
|
|
|
@section{Launcher Creation Unit}
|
|
|
|
@defmodule[launcher/launcher-unit]
|
|
|
|
@defthing[launcher@ unit?]{
|
|
|
|
A unit that imports nothing and exports @racket[launcher^].}
|