2.1 API for Creating Executables🔗ℹ

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.

The create-embedding-executable function combines the bundle with an executable (Racket or GRacket). The write-module-bundle function prints the bundle to the current output port, instead; this stream can be loaded directly by a running program, as long as the read-accept-compiled parameter is true.

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.

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 '(require m). When submodules are available and included, the submodule is given a name by symbol-appending the write form of the submodule path to the enclosing module’s name.

When an embedded module is not listed in the #:modules argument or not given a prefix there, a symbolic name for the embedded module is generated automatically. The names are generated in a deterministic but unspecified way, so that they are not conveniently accessible. The generated names may depend on the path of the first element of mod-list. Modules that were included via a collection-based path remain accessible at run time through their collection-based paths (via a module name resolver that is installed for the embedding executable).

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:

• 'icns (Mac OS) : 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.

  Changed in version 6.3 of package base: All icons in the executable are replaced with icons from the file, instead of setting only certain sizes and depths.

• 'creator (Mac OS) : Provides a 4-character string to use as the application signature.

• 'file-types (Mac OS) : 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) : 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.

• 'resource-files (Mac OS) : extra files to copy into the "Resources" directory of the generated executable.

• '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) : A string to prefix the executable’s path to the Racket and GRacket frameworks (including a separating slash); note that when the prefix start "@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.

• 'embed-dlls? (Windows) : A boolean indicating whether to copy DLLs into the executable, where the default value is #f. Embedded DLLs are instantiated by an internal linking step that bypasses some operating system facilities, so it will not work for all Windows DLLs, but typical DLLs will work as embedded.

• '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? (Unix, Windows, Mac OS) : A boolean; #t for a launcher (see launcher? below) does not preserve the original executable name for (find-system-path 'exec-file); one 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) : 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 the 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 mod-list should be null, literal-files should be null, and literal-sexp should be #f. 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), unless 'forget-exe? is associated to a true value in aux.

The #:variant argument indicates which variant of the original binary to use for embedding. The default is (system-type 'gc); see also current-launcher-variant.

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-filter src-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-imports extras-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).

Changed in version 6.90.0.23 of package base: Added embed-dlls? as an #:aux key.
Changed in version 7.3.0.6: Changed generation of symbolic names for embedded modules to make it deterministic.

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

Changed in version 8.1.0.7 of package base: Changed to actually add a suffix, instead of replacing an existing suffix.

2.2 Installation-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.

The launcher/launcher library provides functions for creating launchers.

2.3 Mac OS Dynamic Library Paths🔗ℹ

Added in version 6.3 of package base.

A single match is expected, and the update assumes enough space for the new path, perhaps because the executable is linked with -headerpad_max_install_names.