1 Running mzc
2 Compiling Modified Modules to Bytecode
3 Creating and Distributing Stand-Alone Executables
4 Packaging Library Collections
5 Compiling and Linking C Extensions
6 Embedding Scheme Modules via C
7 Compiling to Raw Bytecode
8 Compiling to Native Code via C
9 Scheme API for Compilation
Index
On this page:
3.1.1 Scheme 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
3.1.1.1 Executable Creation Signature
compiler: embed^
3.1.1.2 Executable Creation Unit
compiler: embed@
Version: 4.0.1

 

3.1 Stand-Alone Executables from Scheme Code

The command-line flag --exe directs mzc to embed a module, from source or byte code, into a copy of the mzscheme executable. (Under Unix, the embedding executable is actually a copy of a wrapper executable.) The created executable invokes the embedded module on startup. The --gui-exe flag is similar, but it copies the mred 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

  mzc --gui-exe hello hello.ss

produces either "hello.exe" (Windows), "hello.app" (Mac OS X), or "hello" (Unix), which runs the same as invoking the "hello.ss" module in mred.

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 mzc’s --lib flag. 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 Distributing Stand-Alone Executables).

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

The --exe and --gui-exe flags work 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 mzscheme, mred, or DrScheme. However, the executable depends on PLT Scheme shared libraries, and possibly other run-time files declared via define-runtime-path. The executable can be packaged with support libraries to create a distribution, as described in Distributing Stand-Alone Executables.

3.1.1 Scheme API for Creating Executables

 (require compiler/embed)

The compiler/embed library provides a function to embed Scheme code into a copy of MzScheme or MrEd, thus creating a stand-alone Scheme executable. To package the executable into a distribution that is indpendent of your PLT 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 (MzScheme or MrEd). 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.

(create-embedding-executable

 

 

 

dest

 

 

 [

#:modules mod-list

 

 

 

#:literal-files literal-files

 

 

 

#:literal-expression literal-sexp

 

 

 

#:literal-expressions literal-sexps

 

 

 

#:cmdline cmdline

 

 

 

#:mred? mred?

 

 

 

#:variant variant

 

 

 

#:aux aux

 

 

 

#:collects-path collects-path

 

 

 

#:launcher? launcher?

 

 

 

#:verbose? verbose?

 

 

 

#:compiler compile-proc

 

 

 

#:expand-namespace expand-namespace

 

 

 

#:src-filter src-filter

 

 

 

#:on-extension ext-proc

 

 

 

#:get-extra-imports extras-proc])

 

  void?

  dest : path-string?

  

mod-list

 

:

 

(listof (list/c (or/c symbol? (one-of/c #t #f))

                module-path?))

 

 

 

=

 

null

  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

  mred? : any/c = #f

  variant : (one-of/c 'cgc '3m) = (system-type 'gc)

  aux : (listof (cons/c symbol? any/c)) = null

  

collects-path

 

:

 

(or/c false/c

      path-string?

      (listof path-string?))

 

=

 

#f

  launcher? : any/c = #f

  verbose? : any/c = #f

  

compile-proc

 

:

 

(any/c . -> . compiled-expression?)

 

 

 

=

 

(lambda (e)

  (parameterize ([current-namespace

                  expand-namespace])

    (compile e)))

  expand-namespace : namespace? = (current-namespace)

  src-filter : (path? . -> . any) = (lambda (p) #t)

  

ext-proc

 

:

 

(or/c false/c (path-string? boolean? . -> . any))

 

 

 

=

 

#f

  

extras-proc

 

:

 

(path? compiled-module?

 . -> . (listof module-path?))

 

 

 

=

 

(lambda (p m) null)

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

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

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

The #:modules argument mod-list designates modules to be embedded, as described below. The #:literal-files and #:literal-expressions arguments specify literal code to be copied into the executable: the content of each file in literal-files is copied in order (with no intervening space), followed by each element of literal-sexps. The literal-files files or literal-sexps list 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. If literal-sexp is #f, no literal expression is included in the executable. The #:literal-expression (singular) argument is for backward compatibility.

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-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). The prefix can be a symbol, #f to indicate no prefix, or #t to indicate an auto-generated prefix. For example,

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

embeds the module m from the file "m.ss", without prefixing the name of the module; the literal-sexpr argument to go with the above might be '(require m).

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

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:

If the #:collects-path argument is #f, then the created executable maintains its built-in (relative) path to the main "collects" directory – which will be the result of (find-system-path 'collects-dir) when the executable is run – plus a potential list of other directories for finding library collections – which are used to initialize the current-library-collection-paths list in combination with PLTCOLLECTS environment variable. Otherwise, the argument specifies a replacement; it must be either a path, string, or non-empty 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 #:launcher? argument is #t, then no modules should be null, literal-files should be null, literal-sexp should be #f, and the platform should be Windows or Mac OS X. The embedding executable is created in such a way that (find-system-path 'exec-file) produces the source MzScheme or MrEd path instead of the embedding executable (but the result of (find-system-path 'run-file) is still the embedding executable).

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

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

(make-embedding-executable

 

dest

 

 

 

 

 

 

mred?

 

 

 

 

 

 

verbose?

 

 

 

 

 

 

mod-list

 

 

 

 

 

 

literal-files

 

 

 

 

 

 

literal-sexp

 

 

 

 

 

 

cmdline

 

 

 

 

 

 [

aux

 

 

 

 

 

 

launcher?

 

 

 

 

 

 

variant])

 

 

void?

  dest : path-string?

  mred? : any/c

  verbose? : any/c

  

mod-list

 

:

 

(listof (list/c (or/c symbol? (one-of/c #t #f))

                module-path?))

  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 : (one-of/c 'cgc '3m) = (system-type 'gc)

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

(write-module-bundle

 

verbose?

 

 

 

 

 

 

mod-list

 

 

 

 

 

 

literal-files

 

 

 

 

 

 

literal-sexp)

 

 

void?

  verbose? : any/c

  

mod-list

 

:

 

(listof (list/c (or/c symbol? (one-of/c #t #f))

                module-path?))

  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.

(embedding-executable-is-directory? mred?)  boolean

  mred? : any/c

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

(embedding-executable-is-actually-directory? mred?)  boolean?

  mred? : any/c

Indicates whether MzScheme/MrEd executables for the current platform actually correspond to directories. The result is #t under Mac OS X when mred? is #t, #f otherwise.

(embedding-executable-put-file-extension+style+filters mred?)

 

 

(or/c string? false/c)

(listof (one-of/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 MzScheme/MrEd launchers for the current platform were directories form the user’s perspective, the style result is suitable for use with get-directory, and the extension result may be a string indicating a required extension for the directory name.

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

3.1.1.1 Executable Creation Signature

 (require compiler/embed-sig)

compiler:embed^ : signature

Includes the identifiers provided by compiler/embed.

3.1.1.2 Executable Creation Unit

 (require compiler/embed-unit)

compiler:embed@ : unit?

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