2 raco exe: Creating Stand-Alone Executables

▼ |  | raco: Racket Command-Line Tools

1 | raco make: Compiling Source to Bytecode
2 | raco exe: Creating Stand-Alone Executables
3 | raco distribute: Sharing Stand-Alone Executables
4 | raco planet: Automatic Package Distribution
5 | raco pkg: Package Management
6 | raco setup: Installation Management
7 | raco decompile: Decompiling Bytecode
8 | raco demod: Demodularizing Programs
9 | raco link: Library Collection Links
10 | raco pack: Packing Library Collections
11 | raco unpack: Unpacking Library Collections
12 | raco ctool: Working with C Code
13 | raco test: Run tests
14 | raco docs: Documentation Search
15 | raco expand: Macro Expansion
16 | raco read: Reading and Pretty-Printing
17 | raco scribble: Building Documentation
18 | Adding a raco Command
19 | Installation Configuration and Search Paths

► | 2 | raco exe: Creating Stand-Alone Executables

2.1 | API for Creating Executables
2.2 | Installation-Specific Launchers
2.3 | Mac OS Dynamic Library Paths

On this page:

2.1 API for Creating Executables
create-embedding-executable
make-embedding-executable
write-module-bundle
embedding-executable-is-directory?
embedding-executable-is-actually-directory?
embedding-executable-put-file-extension+ style+ filters
embedding-executable-add-suffix
2.1.1 Executable Creation Signature
compiler: embed^
2.1.2 Executable Creation Unit
compiler: embed@
2.1.3 Finding the Racket Executable
find-exe
2.2 Installation-Specific Launchers
2.2.1 Creating Launchers
make-gracket-launcher
make-racket-launcher
make-gracket-program-launcher
make-racket-program-launcher
install-gracket-program-launcher
install-racket-program-launcher
make-mred-launcher
make-mred-program-launcher
install-mred-program-launcher
make-mzscheme-launcher
make-mzscheme-program-launcher
install-mzscheme-program-launcher
2.2.2 Launcher Path and Platform Conventions
gracket-program-launcher-path
racket-program-launcher-path
gracket-launcher-is-directory?
racket-launcher-is-directory?
gracket-launcher-is-actually-directory?
racket-launcher-is-actually-directory?
gracket-launcher-add-suffix
racket-launcher-add-suffix
gracket-launcher-put-file-extension+ style+ filters
racket-launcher-put-file-extension+ style+ filters
mred-program-launcher-path
mred-launcher-is-directory?
mred-launcher-is-actually-directory?
mred-launcher-add-suffix
mred-launcher-put-file-extension+ style+ filters
mzscheme-program-launcher-path
mzscheme-launcher-is-directory?
mzscheme-launcher-is-actually-directory?
mzscheme-launcher-add-suffix
mzscheme-launcher-put-file-extension+ style+ filters
installed-executable-path->desktop-path
installed-desktop-path->icon-path
2.2.3 Launcher Configuration
gracket-launcher-up-to-date?
racket-launcher-up-to-date?
build-aux-from-path
extract-aux-from-path
current-launcher-variant
available-gracket-variants
available-racket-variants
mred-launcher-up-to-date?
mzscheme-launcher-up-to-date?
available-mred-variants
available-mzscheme-variants
2.2.4 Launcher Creation Signature
launcher^
2.2.5 Launcher Creation Unit
launcher@
2.3 Mac OS Dynamic Library Paths
find-matching-library-path
update-matching-library-path

Racket
top contents ← prev up next →

## 2 raco exe: Creating Stand-Alone Executables🔗ℹ

> > > To achieve a faster startup time, instead of trying raco exe, use a smaller base language—such as #lang racket/base instead of #lang racket. Also, ensure that bytecode files are compiled by using raco make. For further improvements, try using raco demod.

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), 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). A submodule is included if its enclosing module is included and the submodule contains a sub-submodule named declare-preserve-for-embedding (where the implementation of the sub-submodule is ignored).

Language reader modules that are used only via #lang are also not automatically embedded. To support dynamic use of #lang with a language specification, supply the ++lang flag to raco exe. The argument after ++lang can be a language name, but more generally it can be text to appear just after #lang. For example, at-exp racket/base makes sense as an argument to ++lang to allow at-exp combined with racket/base as a language for dynamically loaded modules.

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.

When a module is embedded in an executable, it gets a symbolic name instead of its original filesystem-based name. The module-name resolver is configured in the embedding executable to map collection-based module paths to the embedded symbolic name, but no such mapping is created for filesystem paths. By default, a module’s symbolic name is generated in an unspecified but deterministic way where the name starts with #%embedded:, except that the main module is prefixed with #%mzc:. The relative lack of specification for module names can be a problem for language constructs that are sensitive to module names, such as serialization. To take more control over a module’s symbolic name, use the ++named-lib or ++named-file argument to specify a prefix that is appended before the module’s base name to generate a symbolic name.

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 may depend on Racket shared libraries and possibly other run-time files declared via define-runtime-path. Using --embed-dlls on Windows or --orig-exe on Unix may produce an executable that is more stand-alone than otherwise. Options used when building Racket itself affect the degree to which executables are stand-alone.Then standard distribution uses options that make executables as stand-alone as possible. For a Unix build, configuring with --enable-shared makes executables less stand-alone. For a Mac OS build, configuring without --enable-embedfw makes non-GUI executables less stand-alone. In any case, the executable can be packaged with support libraries to create a self-contained 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 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. Beware that the default command-line flags to build into the launcher prevent access to packages that are installed in user scope; use --exf -U to enable access to user-scope packages from the launcher.

- --embed-dlls — On Windows, for a stand-alone executable, copies any needed DLLs into the executable. Embedding DLLs makes the resulting executable truly stand-alone if it does not depend on other external files. Not all DLLs work with embedding, and limitations are mostly related to thread-local storage and resources, but all DLLs within the main Racket distribution work with --embed-dlls.

- --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-path ‹path› — set ‹path› within the executable as the path to the main collection directory; if the path is relative, it will be treated as relative to the executable. The default is to have no path, which means that the current-library-collection-paths and current-library-collection-links parameters are initialized as null when the executable starts. Beware that various other directories are located relative to the main collection directory by default (see Installation Configuration and Search Paths), so that installing ‹path› may allow other directories to be found—intentional or not.

- --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. This mode currently does not prune unreferenced submodules (and it pulls along any dependencies of submodules).

- --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, set the icons for the generated executable to be the content of ‹.icns-path›.

- --orig-exe — on Unix, generate an executable based on the original racket or gracket executable, instead of a wrapper executable that redirects to the original. If the original executable is statically linked to the Racket runtime library, then the resulting executable is similarly stand-alone. Beware that if the original executable links to Racket as a shared library, however, then raco distribute cannot work with executables that are created with --orig-exe (because the wrapper executable normally takes care of finding the shared libraries when the executable is distributed to a different machine).

- --cs — generate an executable based on the CS implementation of Racket, which is the default unless running a raco exe that is based on the BC implementation.

- --3m — generate an executable based on the 3m variant of Racket, which is the default only when running a raco exe that is based on the 3m variant of the BC implementation.

- --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 of the BC implementation.

- ++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.

- ++lang ‹lang› — include modules needed to load modules starting #lang ‹lang› dynamically. The ‹lang› does not have to be a plain language or module name; it might be a more general text sequence, such as at-exp racket/base to support language constructors like at-exp. The initial require for a module read as ‹lang› must be available though the language reader’s get-info function and the 'module-language key; languages implemented with syntax/module-reader support that key automatically.

- ++named-lib ‹prefix› ‹module-path› — like ++lib, but the embedded module’s symbolic name is specified to be ‹prefix› appended before the library file’s base name. Specifying a module’s symbolic name can be useful with language constructs that depend reflexively on a module name, such as a serialization format (where a module name is record so that a function can be found later for deserialization).

- ++named-file ‹prefix› ‹file-path› — include ‹file-path› in the executable, even if it is not referenced by the main program, and use ‹prefix› before the file’s base name as the embedded module’s symbolic name. Since the embedded module’s symbolic name is predictable, the module might be accessed at run time via dynamic-require. A predictable module name can also help with serialized data in the same way as ++named-lib.

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

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

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

- --exf-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.

Changed in version 6.3.0.11: Added support for declare-preserve-for-embedding.
Changed in version 6.90.0.23: Added --embed-dlls.
Changed in version 7.0.0.17: Added ++lang.
Changed in version 7.3.0.6: Added ++named-lib and ++named-file, and changed generation of symbolic names for embedded modules to make it deterministic.

### 2.1 API for Creating Executables🔗ℹ

(require compiler/embed) | package: base

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.

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.

> > procedure
> > (create-embedding-executable |
> > |  | dest |
> > |  | #:modules mod-list |
> > | [ | #:early-literal-expressions early-literal-sexps |
> > |  | #:configure-via-first-module? config-via-first? |
> > |  | #:literal-files literal-files |
> > |  | #:literal-expression literal-sexp |
> > |  | #:literal-expressions literal-sexps |
> > |  | #:cmdline cmdline |
> > |  | #:gracket? gracket? |
> > |  | #:mred? mred? |
> > |  | #:variant variant |
> > |  | #:aux aux |
> > |  | #:collects-path collects-path |
> > |  | #:collects-dest collects-dest |
> > |  | #:launcher? launcher? |
> > |  | #:verbose? verbose? |
> > |  | #:expand-namespace expand-namespace |
> > |  | #:compiler compile-proc |
> > |  | #:src-filter src-filter |
> > |  | #:on-extension ext-proc |
> > |  | #:get-extra-imports extras-proc]) |
> → void?
> dest : path-string?
> | mod-list |  | : |  |
> (listof (or/c (list/c (or/c symbol? #f #t)
> (or/c module-path? path?))
> (list/c (or/c symbol? #f #t)
> (or/c module-path? path?)
> (listof symbol?))))
> early-literal-sexps : list? = null
> config-via-first? : any/c = #f
> literal-files : (listof path-string?) = null
> literal-sexp : any/c = #f
> | literal-sexps |  | : |  | list? |  | = |  |
> (if literal-sexp
> (list literal-sexp)
> null)
> cmdline : (listof string?) = null
> gracket? : any/c = #f
> mred? : any/c = #f
> variant : (or/c 'cgc '3m 'cs) = (system-type 'gc)
> aux : (listof (cons/c symbol? any/c)) = null
> | collects-path |  | : |  |
> (or/c #f
> path-string?
> (listof path-string?))
> |  | = |  | #f
> collects-dest : (or/c #f path-string?) = #f
> launcher? : any/c = #f
> verbose? : any/c = #f
> expand-namespace : namespace? = (current-namespace)
> | compile-proc |  | : |  | (any/c . -> . compiled-expression?)
> |  |  | = |  |
> (lambda (e)
> (parameterize ([current-namespace
> expand-namespace])
> (compile e)))
> src-filter : (path? . -> . any) = (lambda (p) #t)
> ext-proc : (or/c #f (path-string? boolean? . -> . any)) = #f
> | extras-proc |  | : |  |
> (path? compiled-module-expression?
> . -> . (listof module-path?))
> |  |  | = |  | (lambda (p m) null)

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.

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.

> > procedure
> > (make-embedding-executable |  | dest |  |  |  |
> > |  | mred? |  |  |  |
> > |  | verbose? |  |  |  |
> > |  | mod-list |  |  |  |
> > |  | literal-files |  |  |  |
> > |  | literal-sexp |  |  |  |
> > |  | cmdline |  |  |  |
> > | [ | aux |  |  |  |
> > |  | launcher? |  |  |  |
> > |  | variant |  |  |  |
> > |  | collects-path]) |  | → |  | void?
> dest : path-string?
> mred? : any/c
> verbose? : any/c
> | mod-list |  | : |  |
> (listof (or/c (list/c (or/c symbol? #f #t)
> (or/c module-path? path?))
> (list/c (or/c symbol? #f #t)
> (or/c module-path? path?)
> (listof symbol?))))
> literal-files : (listof path-string?)
> literal-sexp : any/c
> cmdline : (listof string?)
> aux : (listof (cons/c symbol? any/c)) = null
> launcher? : any/c = #f
> variant : (or/c 'cgc '3m 'cs) = (system-type 'gc)
> | collects-path |  | : |  |
> (or/c #f
> path-string?
> (listof path-string?))
> |  | = |  | #f

Old (keywordless) interface to create-embedding-executable.

> > procedure
> > (write-module-bundle |  | verbose? |  |  |  |
> > |  | mod-list |  |  |  |
> > |  | literal-files |  |  |  |
> > |  | literal-sexp) |  | → |  | void?
> verbose? : any/c
> | mod-list |  | : |  |
> (listof (or/c (list/c (or/c symbol? #f #t)
> (or/c module-path? path?))
> (list/c (or/c symbol? #f #t)
> (or/c module-path? path?)
> (listof symbol?))))
> literal-files : (listof path-string?)
> literal-sexp : any/c

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.

> procedure (embedding-executable-is-directory? mred?) → boolean
> mred? : any/c

Indicates whether Racket/GRacket executables for the current platform correspond to directories from the user’s perspective. The result is currently #f for all platforms.

> procedure (embedding-executable-is-actually-directory? mred?) → boolean?
> mred? : any/c

Indicates whether Racket/GRacket executables for the current platform actually correspond to directories. The result is #t on Mac OS when mred? is #t, #f otherwise.

> procedure (embedding-executable-put-file-extension+style+filters mred?)
> | → |  |
> (or/c string? #f)
> (listof (or/c 'packages 'enter-packages))
> (listof (list/c string? string?))
> mred? : any/c

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

> > procedure
> > (embedding-executable-add-suffix |  | path |  |  |  |
> > |  | mred?) |  | → |  | path-string?
> path : path-string?
> mred? : any/c

Adds a suitable executable suffix, if it’s not present already.

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

#### 2.1.1 Executable Creation Signature🔗ℹ

(require compiler/embed-sig) | package: compiler-lib

> signature compiler:embed^ : signature

Includes the identifiers provided by compiler/embed.

#### 2.1.2 Executable Creation Unit🔗ℹ

(require compiler/embed-unit) | package: compiler-lib

> value compiler:embed@ : unit?

A unit that imports nothing and exports compiler:embed^.

#### 2.1.3 Finding the Racket Executable🔗ℹ

(require compiler/find-exe) | package: base

> > procedure
> > (find-exe | [ | #:cross? cross? |  |  |  |
> > |  | #:untethered? untethered? |  |  |  |
> > |  | gracket? |  |  |  |
> > |  | variant]) |  | → |  | path?
> cross? : any/c = #f
> untethered? : any/c = #f
> gracket? : any/c = #f
> | variant |  | : |  | (or/c 'cgc '3m 'cs) |  | = |  |
> (if cross?
> (cross-system-type 'gc)
> (system-type 'gc))

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

If cross? is true, the executable is found for the target platform in cross-installation mode.

If untethered? is true, then the original executable is found, instead of an executable that is tethered to a configuration or addon directory via (find-addon-tethered-console-bin-dir) and related functions.

Changed in version 6.2.0.5 of package base: Added the #:untethered? argument.
Changed in version 6.3: Added the #:cross? argument.

### 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.

(require launcher/launcher) | package: base

The launcher/launcher library provides functions for creating launchers.

#### 2.2.1 Creating Launchers🔗ℹ

> > procedure
> > (make-gracket-launcher |  | args |  |  |  |
> > |  | dest |  |  |  |
> > | [ | aux |  |  |  |
> > |  | #:tether-mode tether-mode]) |  | → |  | void?
> args : (listof string?)
> dest : path-string?
> aux : (listof (cons/c symbol? any/c)) = null
> tether-mode : (or/c 'addon 'config #f) = 'addon

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 GRacket; the following additional associations apply to launchers:

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

- 'exe-name (Mac OS, 'script-3m, 'script-cgc or 'script-cs variant) — provides the base name for a '3m-/'cgc-/'cs-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 'main, 'user, 'config-tethered, or 'addon-tethered, indicates that the launcher is being installed to an installation-wide place, a user-specific place, an installation-wide place that embeds the configuration path, or a specific place that embeds an addon-directory path; the install mode, in turn, determines whether and 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.

The tether-mode argument indicates how much to preserve the current installation’s tethering to a configuration directory and/or addon directory based on (find-addon-tether-console-bin-dir) and (find-config-tether-console-bin-dir). The 'addon mode allows full tethering, the 'config mode allows only configuration-directory tethering, and the #f mode disables tethering.

Changed in version 6.5.0.2 of package base: Added the #:tether-mode argument.

> procedure (make-racket-launcher args dest [aux]) → void?
> args : (listof string?)
> dest : path-string?
> aux : (listof (cons/c symbol? any/c)) = null

Like make-gracket-launcher, but for starting Racket. On Mac OS, the 'exe-name aux association is ignored.

> > procedure
> > (make-gracket-program-launcher |  | file |  |  |  |
> > |  | collection |  |  |  |
> > |  | dest) |  | → |  | void?
> file : string?
> collection : string?
> dest : path-string?

Calls make-gracket-launcher with arguments that start the GRacket program implemented by file in collection: (list "-l-" (string-append collection "/" file)). The aux argument to make-gracket-launcher is generated by stripping the suffix (if any) from file, adding it to the path of collection, and passing the result to build-aux-from-path.

> > procedure
> > (make-racket-program-launcher |  | file |  |  |  |
> > |  | collection |  |  |  |
> > |  | dest) |  | → |  | void?
> file : string?
> collection : string?
> dest : path-string?

Like make-gracket-program-launcher, but for make-racket-launcher.

> > procedure
> > (install-gracket-program-launcher |  | file |  |  |  |
> > |  | collection |  |  |  |
> > |  | name) |  | → |  | void?
> file : string?
> collection : string?
> name : string?

Same as

> (make-gracket-program-launcher
> file collection
> (gracket-program-launcher-path name))

> > procedure
> > (install-racket-program-launcher |  | file |  |  |  |
> > |  | collection |  |  |  |
> > |  | name) |  | → |  | void?
> file : string?
> collection : string?
> name : string?

Same as

> (make-racket-program-launcher
> file collection
> (racket-program-launcher-path name))

> procedure (make-mred-launcher args dest [aux]) → void?
> args : (listof string?)
> dest : path-string?
> aux : (listof (cons/c symbol? any/c)) = null
> > procedure
> > (make-mred-program-launcher |  | file |  |  |  |
> > |  | collection |  |  |  |
> > |  | dest) |  | → |  | void?
> file : string?
> collection : string?
> dest : path-string?
> > procedure
> > (install-mred-program-launcher |  | file |  |  |  |
> > |  | collection |  |  |  |
> > |  | name) |  | → |  | void?
> file : string?
> collection : string?
> name : string?

Backward-compatible version of make-gracket-launcher, etc., that adds "-I" "scheme/gui/init" to the start of the command-line arguments.

> procedure (make-mzscheme-launcher args dest [aux]) → void?
> args : (listof string?)
> dest : path-string?
> aux : (listof (cons/c symbol? any/c)) = null
> > procedure
> > (make-mzscheme-program-launcher |  | file |  |  |  |
> > |  | collection |  |  |  |
> > |  | dest) |  | → |  | void?
> file : string?
> collection : string?
> dest : path-string?
> > procedure
> > (install-mzscheme-program-launcher |  | file |  |  |  |
> > |  | collection |  |  |  |
> > |  | name) |  | → |  | void?
> file : string?
> collection : string?
> name : string?

Backward-compatible version of make-racket-launcher, etc., that adds "-I" "scheme/init" to the start of the command-line arguments.

#### 2.2.2 Launcher Path and Platform Conventions🔗ℹ

> > procedure
> > (gracket-program-launcher-path |  | name |  |  |  |
> > | [ | #:user? user? |  |  |  |
> > |  | #:tethered? tethered? |  |  |  |
> > |  | #:console? console?]) |  | → |  | path?
> name : string?
> user? : any/c = #f
> tethered? : any/c = #f
> console? : any/c = #f

Returns a pathname for an executable called something like name in

- the Racket installation — when user? is #f and tethered? is #f;

- the user’s Racket executable directory — when user? is #t and tethered? is #f;

- an additional executable directory for executables tethered to a particular configuration directory — when user? is #f and tethered? is #t; or

- an additional executable directory for executables tethered to a particular addon and configuration directory — when user? is #t and tethered? 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, the ".app" suffix is appended to name.

If console? is true, then the path is in the console executable directory, such as the one reported by (find-console-bin-dir), instead of the GUI executable directory, such as the one reported by (find-gui-bin-dir).

Changed in version 6.5.0.2 of package base: Added the #:tethered? argument.
Changed in version 6.8.0.2: Added the #:console? argument.

> > procedure
> > (racket-program-launcher-path |  | name |  |  |  |
> > | [ | #:user? user? |  |  |  |
> > |  | #:tethered? tethered? |  |  |  |
> > |  | #:console? console?]) |  | → |  | path?
> name : string?
> user? : any/c = #f
> tethered? : any/c = #f
> console? : any/c = #f

Returns the same path as (gracket-program-launcher-path name #:user? user? #:tethered tethered? #:console? console?).

Changed in version 6.5.0.2 of package base: Added the #:tethered? argument.
Changed in version 6.8.0.2: Added the #:console? argument.

> procedure (gracket-launcher-is-directory?) → boolean?

Returns #t if GRacket launchers for the current platform are directories from the user’s perspective. For all currently supported platforms, the result is #f.

> procedure (racket-launcher-is-directory?) → boolean?

Like gracket-launcher-is-directory?, but for Racket launchers.

> procedure (gracket-launcher-is-actually-directory?) → boolean?

Returns #t if GRacket launchers for the current platform are implemented as directories from the filesystem’s perspective. The result is #t for Mac OS, #f for all other platforms.

> procedure (racket-launcher-is-actually-directory?) → boolean?

Like gracket-launcher-is-actually-directory?, but for Racket launchers. The result is #f for all platforms.

> procedure (gracket-launcher-add-suffix path-string?) → path?
> path-string? : path

Returns a path with a suitable executable suffix added, if it’s not present already.

> procedure (racket-launcher-add-suffix path-string?) → path?
> path-string? : path

Like gracket-launcher-add-suffix, but for Racket launchers.

> procedure (gracket-launcher-put-file-extension+style+filters)
> | → |  |
> (or/c string? #f)
> (listof (or/c 'packages 'enter-packages))
> (listof (list/c string? string?))

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

> procedure (racket-launcher-put-file-extension+style+filters)
> | → |  |
> (or/c string? #f)
> (listof (or/c 'packages 'enter-packages))
> (listof (list/c string? string?))

Like gracket-launcher-get-file-extension+style+filters, but for Racket launchers.

> > procedure
> > (mred-program-launcher-path |  | name |  |  |  |
> > | [ | #:user? user? |  |  |  |
> > |  | #:tethered? tethered?]) |  | → |  | path?
> name : string?
> user? : any/c = #f
> tethered? : any/c = #f
> procedure (mred-launcher-is-directory?) → boolean?
> procedure (mred-launcher-is-actually-directory?) → boolean?
> procedure (mred-launcher-add-suffix path-string?) → path?
> path-string? : path
> procedure (mred-launcher-put-file-extension+style+filters)
> | → |  |
> (or/c string? #f)
> (listof (or/c 'packages 'enter-packages))
> (listof (list/c string? string?))

Backward-compatible aliases for gracket-program-launcher-path, etc.

Changed in version 6.5.0.2 of package base: Added the #:tethered? argument.

> > procedure
> > (mzscheme-program-launcher-path |  | name |  |  |  |
> > | [ | #:user? user? |  |  |  |
> > |  | #:tethered? tethered?]) |  | → |  | path?
> name : string?
> user? : any/c = #f
> tethered? : any/c = #f
> procedure (mzscheme-launcher-is-directory?) → boolean?
> procedure (mzscheme-launcher-is-actually-directory?) → boolean?
> procedure (mzscheme-launcher-add-suffix path-string?) → path?
> path-string? : path
> procedure (mzscheme-launcher-put-file-extension+style+filters)
> | → |  |
> (or/c string? #f)
> (listof (or/c 'packages 'enter-packages))
> (listof (list/c string? string?))

Backward-compatible aliases for racket-program-launcher-path, etc.

Changed in version 6.5.0.2 of package base: Added the #:tethered? argument.

> > procedure
> > (installed-executable-path->desktop-path |  | exec-path |
> > |  | user? |
> > |  | tethered?) |
> → (or/c (and/c path? complete-path?) #f)
> exec-path : path-string?
> user? : any/c
> tethered? : any/c

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). The tethered? argument should be true for a tethered install. The result can be #f only when tethered? is true and find-addon-tethered-apps-dir (when user? is true) or find-config-tethered-apps-dir (when user? is #f) returns #f.

Changed in version 8.3.0.11 of package base: Added the tethered? argument.

> > procedure
> > (installed-desktop-path->icon-path |  | desktop-path |
> > |  | user? |
> > |  | suffix) |
> → (and/c path? complete-path?)
> desktop-path : path-string?
> user? : any/c
> suffix : bytes?

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".

#### 2.2.3 Launcher Configuration🔗ℹ

> procedure (gracket-launcher-up-to-date? dest aux) → boolean?
> dest : path-string?
> aux : (listof (cons/c symbol? any/c))

Returns #t if the GRacket launcher dest does not need to be updated, assuming that dest is a launcher and its arguments have not changed.

> procedure (racket-launcher-up-to-date? dest aux) → boolean?
> dest : path-string?
> aux : (listof (cons/c symbol? any/c))

Analogous to gracket-launcher-up-to-date?, but for a Racket launcher.

> procedure (build-aux-from-path path) → (listof (cons/c symbol? any/c))
> path : path-string?

Creates an association list suitable for use with make-gracket-launcher or create-embedding-executable. It builds associations by adding to path suffixes, such as ".icns", checking whether such a file exists, and calling extract-aux-from-path if so. The results from all recognized suffixes are appended together.

> procedure (extract-aux-from-path path) → (listof (cons/c symbol? any/c))
> path : path-string?

Creates an association list suitable for use with make-gracket-launcher or create-embedding-executable. It builds associations by recognizing the suffix of path, where the recognized suffixes are as follows:

- ".icns" → 'icns file for use on Mac OS

- ".ico" → 'ico file for use on Windows or Unix

- ".png" → 'png file for use on Unix

- ".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

- ".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

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

- ".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 to absolute paths; for use on Windows

> parameter (current-launcher-variant) → symbol?
> (current-launcher-variant variant) → void?
> 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 (system-type 'gc). On Unix and Windows, the possibilities are 'cgc, '3m, and 'cs. On Mac OS, the 'script-cgc, 'script-3m, and 'script-cs variants are also available for GRacket launchers.

> procedure (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 '3m, 'cgc, or 'cs— whichever is the result of (system-type 'gc)—and may include the others, as well as 'script-3m, 'script-cgc, and/or 'script-cs on Mac OS.

> procedure (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 '3m, 'cgc, or 'cs—whichever is the result of (system-type 'gc)—and may include the others.

> procedure (mred-launcher-up-to-date? dest aux) → boolean?
> dest : path-string?
> aux : (listof (cons/c symbol? any/c))
> procedure (mzscheme-launcher-up-to-date? dest aux) → boolean?
> dest : path-string?
> aux : (listof (cons/c symbol? any/c))
> procedure (available-mred-variants) → (listof symbol?)
> procedure (available-mzscheme-variants) → (listof symbol?)

Backward-compatible aliases for gracket-launcher-up-to-date?, etc.

#### 2.2.4 Launcher Creation Signature🔗ℹ

(require launcher/launcher-sig) | package: compiler-lib

> signature launcher^ : signature

Includes the identifiers provided by launcher/launcher.

#### 2.2.5 Launcher Creation Unit🔗ℹ

(require launcher/launcher-unit) | package: compiler-lib

> value launcher@ : unit?

A unit that imports nothing and exports launcher^.

### 2.3 Mac OS Dynamic Library Paths🔗ℹ

(require compiler/exe-dylib-path) | package: base

The compiler/exe-dylib-path library provides functions for reading and adjusting dynamic-library references in a Mac OS executable.

Added in version 6.3 of package base.

> > procedure
> > (find-matching-library-path |  | exe-path |  |  |  |
> > |  | library-str) |  | → |  | (or/c #f string?)
> exe-path : path-string?
> library-str : string?

Searches dynamic-linking information in exe-path for a library reference whose name includes library-str and returns the executable’s path to the library for the first match. If no match is found, the result is #f.

> > procedure
> > (update-matching-library-path |  | exe-path |  |  |  |
> > |  | library-str |  |  |  |
> > |  | library-path-str) |  | → |  | void?
> exe-path : path-string?
> library-str : string?
> library-path-str : string?

Searches dynamic-linking information in exe-path for each library reference whose name includes library-str and replaces the executable’s path to that library with library-path-str.

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.

top contents ← prev up next →