2raco exe: Creating Stand-Alone Executables

Use a smaller base language to achieve a faster startup time such
as #langracket/base instead of
#langracket rather than relying on raco
exe.

Compiled code produced by raco make relies on Racket
executables to provide run-time support to the compiled code. However,
raco exe can package code together with its run-time support to
form an executable, and raco distribute can package the
executable into a distribution that works on other machines. Running
an executable produced by raco exe will not improve performance
over raco make.

The raco exe command embeds a module, from source or byte
code, into a copy of the racket executable. (On Unix, the
embedding executable is actually a copy of a wrapper executable.) The
created executable invokes the embedded module on startup. The
--gui flag causes the program to be embedded in a copy of the
gracket executable. If the embedded module refers to other
modules via require, then the other modules are also included
in the embedding executable.

For example, the command

raco exe --gui hello.rkt

produces either "hello.exe" (Windows), "hello.app"
(Mac OS X), or "hello" (Unix), which runs the same as running
the "hello.rkt" module in gracket.

Library modules or other files that are referenced
dynamically—through eval, load, or
dynamic-require—are not automatically embedded into the
created executable. Such modules can be explicitly included using the
++lib flag to raco exe. Alternately, use
define-runtime-path to embed references to the run-time files
in the executable; the files are then copied and packaged together
with the executable when creating a distribution (as described in
raco distribute: Sharing Stand-Alone Executables).

Modules that are implemented directly by extensions—i.e., extensions
that are automatically loaded from (build-path"compiled""native"(system-library-subpath)) to satisfy a
require—are treated like other run-time files: a generated
executable uses them from their original location, and they are copied
and packaged together when creating a distribution.

The raco exe command works only with module-based programs. The
compiler/embed library provides a more general
interface to the embedding mechanism.

A stand-alone executable is “stand-alone” in the sense that you can
run it without starting racket, gracket, or
DrRacket. However, the executable depends on Racket shared libraries,
and possibly other run-time files declared via
define-runtime-path. The executable can be packaged with
support libraries to create a distribution using raco
distribute, as described in raco distribute: Sharing Stand-Alone Executables.

The raco exe command accepts the following command-line flags:

-o‹file› — create the executable as
‹file›, adding a suffix to ‹file› as appropriate
for the platform and executable type. On Mac OS X in --gui
mode, ‹file› is actually a bundle directory, but it appears
as a file within Finder.

--gui — create a graphical executable based on
gracket instead of racket.

-l or --launcher — create a launcher (see
Installation-Specific Launchers), instead of a stand-alone executable. Flags
such as --config-path, --collects-path, and
--lib have no effect on launchers.

--config-path‹path› — set ‹path›
within the executable as the path to the configuration
directory; if the path is relative, it will be treated as relative
to the executable. The default path is "etc", with the
expectation that no such directory will exist at run time.

--collects-dest‹path› — write modules to be
included with the executable into ‹path›
(relative to the current directory), instead of embedded within the
executable. The --collects-dest flag normally makes sense
only in combination with --collects-path.

--ico‹.ico-path› — on Windows, set the icons
for the generated executable to ones extracted from
‹.ico-path›; see create-embedding-executable’s
use of the 'ico auxiliary association for more information
about expected icon sizes and transformations.

--icns‹.icns-path› — on Mac OS X, set the icons
for the generated executable to be the content of
‹.icns-path›.

--orig-exe — generate an executable that refers to
the original racket or gracket executable,
instead of making a copy. This flag is rarely useful, because the
part of the executable that is copied is normally small, and
raco distribute does not work with executables that are
created with --orig-exe.

--3m — generate an executable based on the 3m
variant of Racket, which is the default unless running a raco
exe that is based on the CGC variant.

--cgc — generate an executable based on the CGC
variant of Racket, which is the default only when running a
raco exe that is based on the CGC variant.

++aux‹file› — attach information to the
executable based on ‹file›’s suffix; see
extract-aux-from-path for a list of recognized suffixes
and meanings, and see create-embedding-executable’s use of
auxiliary association for more specific information about how each
kind of file is used.

++lib‹module-path› — include ‹module-path›
in the executable, even if it is not referenced by the main program,
so that it is available via dynamic-require.

++exfl‹flag› — provide the ‹flag›
command-line argument on startup to the embedded racket or
gracket.

--exfl‹flag› — remove ‹flag› from the
command-line arguments to be provided on startup to the embedded
racket or gracket.

--exfl-clear — remove all command-line arguments to be
provided on startup to the embedded racket or
gracket.

--exfl-show — show (without changing) the command-line
arguments to be provided on startup to the embedded
racket or gracket.

-v — report progress verbosely.

--vv — report progress more verbosely than -v.

2.1API for Creating Executables

The compiler/embed library provides a function to
embed Racket code into a copy of Racket or GRacket, thus creating a
stand-alone Racket executable. To package the executable into a
distribution that is independent of your Racket installation, use
assemble-distribution from
compiler/distribute.

Embedding walks the module dependency graph to find all modules needed
by some initial set of top-level modules, compiling them if needed,
and combining them into a “module bundle.” In addition to the module
code, the bundle extends the module name resolver, so that modules can
be required with their original names, and they will be
retrieved from the bundle instead of the filesystem.

Copies the Racket (if gracket? and mred? are
#f) or GRacket (otherwise) binary, embedding code into the
copied executable to be loaded on startup. On Unix, the binary is
actually a wrapper executable that execs the original; see also the
'original-exe? tag for aux.

The embedding executable is written to dest, which is
overwritten if it exists already (as a file or directory).

The embedded code consists of module declarations followed by
additional (arbitrary) code. When a module is embedded, every module
that it imports is also embedded. Library modules are embedded so that
they are accessible via their lib paths in the initial
namespace except as specified in mod-list, other modules
(accessed via local paths and absolute paths) are embedded with a
generated prefix, so that they are not directly accessible.

The #:modules argument mod-list designates modules
to be embedded, as described below. The #:early-literal-expressions, #:literal-files, and
#:literal-expressions arguments specify literal code to be
copied into the executable: each element of early-literal-sexps
is copied in order, then
the content of each file in
literal-files in order (with no intervening spaces),
and then each element of literal-sexps. The
literal-files files or early-literal-sexps or literal-sexps lists can
contain compiled bytecode, and it’s possible that the content of the
literal-files files only parse when concatenated; the files
and expression are not compiled or inspected in any way during the
embedding process. Beware that the initial namespace contains no
bindings; use compiled expressions to bootstrap the namespace.
The #:literal-expression
(singular) argument is for backward compatibility.

If the #:configure-via-first-module? argument is specified as
true, then the language of the first module in mod-list is
used to configure the run-time environment before the expressions
added by #:literal-files and #:literal-expressions
are evaluated, but after the expressions of #:early-literal-expressions. See also Language Run-Time Configuration.

The #:cmdline argument cmdline contains command-line
strings that are prefixed onto any actual command-line arguments that
are provided to the embedding executable. A command-line argument that
evaluates an expression or loads a file will be executed after the
embedded code is loaded.

Each element of the #:modules argument mod-list is a
two- or three-item list, where the first item is a prefix for the
module name, and the second item is a module path datum (that’s in the
format understood by the default module name resolver), and the third
is a list of submodule names to be included if they are available. The
prefix can be a symbol, #f to indicate no prefix, or
#t to indicate an auto-generated prefix. For example,

'((#f"m.rkt"))

embeds the module m from the file "m.rkt", without
prefixing the name of the module; the literal-sexpr argument
to go with the above might be '(requirem). When submodules
are available and included, the submodule is given a name by
symbol-appending the write form of submodule path to the
enclosing module’s name.

Modules are normally compiled before they are embedded into the target
executable; see also #:compiler and #:src-filter
below. When a module declares run-time paths via
define-runtime-path, the generated executable records the
path (for use both by immediate execution and for creating a
distribution that contains the executable).

If collects-dest is a path instead of #f, then
instead of embedding collection-based modules into the executable, the
modules (in compiled form, only) are copied into collections in the
collects-dest directory.

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 also build-aux-from-path. The
currently supported keys are as follows:

'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 (RGBA) depths; the icons are copied
and generated from any 16x16, 32x32, and 48x48 icons in the
".ico" file.

'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 two-element list, where the
first (key) element is a string recognized by Finder, and the
second element is a plist value (see
xml/plist). See "drracket.filetypes"
in the "drracket" collection for an example.

'uti-exports (Mac OS X) : Provides a list of
association lists, one for each Uniform Type
Identifier (UTI) exported by the executable; each association
is a two-element list, where the first (key) element is a
string recognized in a UTI declaration, and the second element
is a plist value (see xml/plist). See
"drracket.utiexports" in the "drracket"
collection for an example.

'config-dir : A string/path to a directory that
contains configuration information, such as
"config.rtkd" (see Installation Configuration and Search Paths). If no
value is supplied, the path is left as-is and converted to
absolute form as needed. If #f is supplied, the path
is left as-is (in potentially relative form). Note that if
collects-path is provided as an empty list, then
the configuration-directory path is not used by Racket’s
start up process (in contrast to a normal Racket start-up,
where the configuration directory is consulted for information
about collection link files).

'framework-root (Mac OS X) : A string to prefix the
executable’s path to the Racket and GRacket frameworks
(including a separating slash); note that when the prefix
starts "@executable_path/" works for a
Racket-based application, the corresponding prefix start for
a GRacket-based application is
"@executable_path/../../../"; if #f is
supplied, the executable’s framework path is left as-is,
otherwise the original executable’s path to a framework is
converted to an absolute path if it was relative.

'dll-dir (Windows) : A string/path to a directory
that contains Racket DLLs needed by the executable, such as
"racket‹version›.dll", or a boolean; a path
can be relative to the executable; if #f is supplied,
the path is left as-is; if #t is supplied, the path
is dropped (so that the DLLs must be in the system directory
or the user’s PATH); if no value is supplied the
original executable’s path to DLLs is converted to an absolute
path if it was relative.

'subsystem (Windows) : A symbol, either
'console for a console application or
'windows for a consoleless application; the default
is 'console for a Racket-based application and
'windows for a GRacket-based application; see also
'single-instance?, below.

'single-instance? (Windows) : A boolean for
GRacket-based apps; the default is #t, which means that
the app looks for instances of itself on startup and merely
brings the other instance to the front; #f means that
multiple instances are expected.

'forget-exe? (Windows, Mac OS X) : A boolean;
#t for a launcher (see launcher? below) 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.

'original-exe? (Unix) : A boolean; #t means
that the embedding uses the original Racket or GRacket
executable, instead of a wrapper binary that execs the
original; the default is #f.

'relative? (Unix, Windows, Mac OS X) : A boolean;
#t means that, to the degree that the generated
executable must refer to another, it can use a relative path
(so the executables can be moved together, but not
separately), and it implies #f for
'config-dir, 'framework-dir, and
'dll-dir, unless those are explicitly provided; a
#f value (the default) means that absolute paths
should be used (so the generated executable can be moved).

'wm-class (Unix) : A string; used as the default
WM_CLASS program class for the program’s windows.

If the #:collects-path argument is #f, then the
created executable maintains its built-in (relative) path to the main
"collects" directory—which will be the result of
(find-system-path'collects-dir) when the executable is
run—plus a potential list of other directories for finding library
collections—which are used to initialize the
current-library-collection-paths list in combination with
PLTCOLLECTS environment variable. Otherwise, the argument
specifies a replacement; it must be either a path, string, or
list of paths and strings. In the last case, the first path
or string specifies the main collection directory, and the rest are
additional directories for the collection search path (placed, in
order, after the user-specific "collects" directory, but
before the main "collects" directory; then the search list is
combined with PLTCOLLECTS, if it is defined). If the list
is empty, then (find-system-path'collects-dir) will return
the directory of the executable, but current-library-collection-paths
is initialized to an empty list, and
use-collection-link-paths is set to false to disable the
use of collection links files.

If the #:launcher? argument is #t, then
lid-list should be null, literal-files should be
null, literal-sexp should be #f, and the platform
should be Windows or Mac OS X. The embedding executable is created in
such a way that (find-system-path'exec-file) produces the
source Racket or GRacket path instead of the embedding executable (but
the result of (find-system-path'run-file) is still the
embedding executable).

The #:compiler argument is used to compile the source of
modules to be included in the executable (when a compiled form is not
already available). It should accept a single argument that is a
syntax object for a module form. The default procedure uses
compile parameterized to set the current namespace to
expand-namespace.

The #:expand-namespace argument selects a namespace for
expanding extra modules (and for compiling using the default
compile-proc). Extra-module expansion is needed to detect
run-time path declarations in included modules, so that the path
resolutions can be directed to the current locations (and, ultimately,
redirected to copies in a distribution).

The #:src-filtersrc-filter argument takes a path and returns true if
the corresponding file source should be included in the embedding
executable in source form (instead of compiled form), #f
otherwise. The default returns #f for all paths. Beware that
the current output port may be redirected to the result executable
when the filter procedure is called. Each path given to
src-filter corresponds to the actual file name (e.g.,
".ss"/".rkt" conversions have been applied as needed
to refer to the existing file).

If the #:on-extension argument is a procedure, the procedure
is called when the traversal of module dependencies arrives at an
extension (i.e., a DLL or shared object). The default, #f,
causes a reference to a single-module extension (in its current
location) to be embedded into the executable. The procedure is called
with two arguments: a path for the extension, and a #f (for
historical reasons).

The #:get-extra-importsextras-proc argument takes a source pathname and
compiled module for each module to be included in the executable. It
returns a list of quoted module paths (absolute, as opposed to
relative to the module) for extra modules to be included in the
executable in addition to the modules that the source module
requires. For example, these modules might correspond to
reader extensions needed to parse a module that will be included as
source, as long as the reader is referenced through an absolute module
path. Each path given to extras-proc corresponds to the
actual file name (e.g., ".ss"/".rkt" conversions
have been applied as needed to refer to the existing file).

Like make-embedding-executable, but the module bundle is
written to the current output port instead of being embedded into an
executable. The output of this function can be read to load
and instantiate mod-list and its dependencies, adjust the
module name resolver to find the newly loaded modules, evaluate the
forms included from literal-files, and finally evaluate
literal-sexpr. The read-accept-compiled parameter
must be true to read the stream.

Returns three values suitable for use as the extension,
style, and filters arguments to put-file,
respectively.

If Racket/GRacket launchers for the current platform were directories
form the user’s 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.

2.1.3Finding the Racket Executable

Finds the path to the racket or gracket (when
gracket? is true) executable.

2.2Installation-Specific Launchers

A launcher is similar to a stand-alone executable, but a
launcher is usually smaller and can be created more quickly, because
it depends permanently on the local Racket installation and the
program’s sources. In the case of Unix, a launcher is simply a shell
script that runs racket or gracket. Launchers
cannot be packaged into a distribution using raco
distribute. The raco exe command creates a launcher when the
-l or --launcher flag is specified.

2.2.1Creating Launchers

Creates the launcher dest, which starts GRacket with the
command-line arguments specified as strings in 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 dest exists already, as either a file
or directory, it is replaced.

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 also build-aux-from-path. See
create-embedding-executable for a list that applies to both
stand-alone executables and launchers on Windows and Mac OS X GRacket;
the following additional associations apply to launchers:

'independent? (Windows) — a boolean; #t
creates an old-style launcher that work with any
Racket or GRacket binary, like setup-plt.exe. No other
aux associations are used for an old-style launcher.

'exe-name (Mac OS X, 'script-3m or
'script-cgc variant) — provides the base name for a
'3m-/'cgc-variant launcher, which the script
will call ignoring args. If this name is not provided,
the script will go through the GRacket executable as usual.

'exe-is-gracket (when 'exe-name is used) —
indicates that 'exe-name refers to the GRacket
executable, which is potentially in a "lib"
subdirectory instead of with other GUI applications.

'relative? (all platforms) — a boolean, where
#t means that the generated launcher should find the
base GRacket executable through a relative path.

'install-mode (Windows, Unix) — either
'user or 'main, indicates that the launcher
is being installed to a user-specific place or to an
installation-wide place, which in turn determines where to
record 'start-menu, 'extension-registry,
and/or 'desktop information.

'start-menu (Windows) — a boolean or real number;
#t indicates that the launcher should be in the
Start menu by an installer that includes the
launcher. A number value is treated like #t, but also
requests that the installer automatically start the
application, where the number determines a precedence relative
to other launchers that may request starting. A
'start-menu value is used only when
'install-mode is also specified.

'extension-register (Windows) — a list of document
types for file-extension registrations to be performed by an
installer. Each document type is described by a list of six
items:

a human-readable string describing the document
type, such as "Racket Document";

a string to use as a key for the document type,
such as "Racket.Document";

a list of strings, where each string is a file
extension without the dot, such as '("rkt""rktl""rktd");

a path to a file that supplies the icon, such as
"doc.ico";

a string to represent the command line to handle a
document with a matching extension, such as
"\"%1\"", where the string will be prefixed
with a path to the launcher, and where %1
will be replaced with the document path

An 'extension-registry value is used only when
'install-mode is also specified.

'desktop (Unix) — a string containing the content of
a ".desktop" file for the launcher, where Exec
and Icon entries are added automatically. If an Exec
entry exists in the string, and if its value starts with a
non-empty sequence of alpha-numeric ASCII characters followed
by a space, then the space and remainder of the value is
appended to the automatically generated value.
The ".desktop" file is written to the directory produced by
(find-apps-dir) or (find-user-apps-dir). A
'desktop value is used only when
'install-mode is also specified.

'png (Unix) : An icon file path (suffix
".png") to be referenced by a ".desktop"
file (if any); a 'png value takes precedence over a
'ico value, but neither is used unless a
'desktop value is also present.

'ico (Unix, in addition to more general Windows use)
: An icon file path (suffix ".ico") that is used in
the same way as 'png if no 'png value is
available.

For Unix/X, the script created by 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 args, they are spliced in after any X Windows flags
already 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.

2.2.2Launcher Path and Platform Conventions

Returns a pathname for an executable called something like name
in the Racket installation (if user? is #f) or the
user’s Racket executable directory (if user? is #t).
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 Racket installation. For Mac OS X, the ".app" suffix
is appended to name.

Returns three values suitable for use as the extension,
style, and filters arguments to put-file,
respectively.

If GRacket launchers for the current platform were directories form the
user’s 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.

Returns a path for a ".desktop" file to describe the
installed executable at exec-path. Only the filename part of
exec-path is used. The user? argument should be true
if exec-path is installed in a user-specific location (in
which case the result path will also be user-specific).

Returns a path for an icon file to be referenced by the
"desktop" file at desktop-path. Only the filename
part of desktop-path is used. The user? argument
should be true if desktop-path is installed in a
user-specific location (in which case the result path will also be
user-specific). The suffix argument provides the icon-file
suffix, normally either #"png" or #"ico".

".lch" → 'independent? as #t
(the file content is ignored) for use on Windows

".creator" → 'creator as the initial
four characters in the file for use on Mac OS X

".filetypes" → 'file-types as
read content (a single S-expression), and
'resource-files as a list constructed by finding
"CFBundleTypeIconFile" entries in 'file-types
(and filtering duplicates); for use on Mac OS X

".utiexports" → 'uti-exports as
read content (a single S-expression); for use on
Mac OS X

".wmclass" → 'wm-class as the literal
content, removing a trailing newline if any; for use on Unix

".desktop" → 'desktop as the literal
content; for use on Unix

".startmenu" → 'start-menu as the file
content if it reads as a real number, #t
otherwise, for use on Windows

".extreg" → 'extension-register as
read content (a single S-expression), but with
relative (to the ".extreg" file) paths converted
absolute; for use on Windows

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 (system-type'gc). On Unix and Windows, the
possibilities are 'cgc and '3m. On Mac OS X, the
'script-3m and 'script-cgc variants are also
available for GRacket launchers.

Returns a list of symbols corresponding to available variants of GRacket
in the current Racket installation. The list normally includes at
least one of '3m or 'cgc— whichever is the result
of (system-type'gc)—and may include the other, as well as
'script-3m and/or 'script-cgc on Mac OS X.

Returns a list of symbols corresponding to available variants of
Racket in the current Racket installation. The list normally
includes at least one of '3m or 'cgc—whichever is
the result of (system-type'gc)—and may include the other.