2 raco exe: Creating Stand-Alone Executables

2 raco exe: Creating Stand-Alone Executables
raco
Racket Command-
Line Tools
raco make
Compiling Source to Bytecode
raco exe
Creating Stand-
Alone Executables
raco distribute
Sharing Stand-
Alone Executables
raco planet
Automatic Package Distribution
raco pkg
Package Management
raco setup
Installation Management
raco decompile
Decompiling Bytecode
raco demod
Demodularizing Programs
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
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 →
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
require
d 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
load
ed 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
parameterize
current-namespace
expand-namespace
compile
src-filter
path?
->
any
lambda
#t
ext-proc
or/c
#f
path-string?
boolean?
->
any
#f
extras-proc
path?
compiled-module-expression?
->
listof
module-path?
lambda
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
exec
s 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
from the file
"m.rkt"
, without
prefixing the name of the module; the
literal-sexpr
argument
to go with the above might be
require
. 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
exec
s 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
require
s. 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
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
".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
read
s 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 →