Next: Core: core.ss
Up: MzLib Libraries
Previous: Compatibility: compat.ss
Files: compile.ss, compileu.ss, compiler.ss, compiles.ss
Signature: mzlib:compile^
Unit: mzlib:compile@, no imports
(compile-file src dest [flags preprocess]) PROCEDURE
Compiles the Scheme file(s) src and saves the compiled code to
dest. The src and dest arguments are usually
filenames. The src argument can also be an input port or a list
of filenames and/or input ports. If a list of inputs is provided for
src, they are compiled to dest as if they were
concatenated (in order) in a single input. The dest argument
can also be an output port. If an input or output port is provided,
the port is not closed when compilation is finished. If
dest is a filename and the file already exists, the existing
file is truncated (if possible) or replaced.
The flags argument is a list of symbol flags, defaultly
null. The possible flags are:
- 'ignore-macro-definitions -- disables special
handling for define-macro, define-id-macro, and
define-expansion-time forms (and their #% forms; see
below).
- 'strip-macro-definitions -- performs special
handling for define-macro, define-id-macro, and
define-expansion-time (and their #% forms; see below),
but no compiled expression is written to the compiled file.
- 'expand-load -- top-level load,
load-relative, and load/cd expressions in the
source(s) are expanded and compiled directly into
dest. Load-expansion is performed recursively within loaded
files.
- 'expand-require-library -- top-level
require-library and #%require-library expressions
in the source(s) are replaced with the source of the library.
- 'ignore-require-library -- top-level
require-library expressions are not handled specially; the
default handling of require-library is described below.
- 'preserve-elaborations -- instead of evaluating
the expressions within begin-elaboration-time expressions
at macro-expansion-time, the expressions are preserved and evaluated
when the compiled expression is loaded; the result of this run-time
evaluation is then itself evaluated to get semantics similar to the
usual begin-elaboration-time semantics. Thus,
(begin-elaboration-time expr ) becomes (eval (eval (quote (begin expr )))). This flag does not
affect the expansion of #%begin-elaboration-time forms.
The output file starts with 'e followed by a space, an
annotation used by load/use-compiled when the
use-compiled-file-kinds parameter is set to
'non-elaboration (see
section 9.4.1.7).
- 'also-preserve-elaborations -- like
'preserve-elaborations, but the expressions in a
begin-elaboration-time form are also evaluated at
expansion time.
- 'preserve-constructions -- modifies the semantics
of begin-construction-time in the same way that
'preserve-elaborations modifies
begin-elaboration-time.
- 'also-preserve-constructions -- like
'preserve-constructions, but the expressions in a
begin-construction-time form are also evaluated at
expansion time.
- 'only-expand -- expands, but does not compile,
the expressions from the source(s).
- 'no-warnings -- suppresses warnings (written to
the current error port) about ill-formed top-level
require-library or load expressions that are recognized
but cannot be expanded.
- 'use-current-namespace -- does not create a new
namespace for compiling the source(s). The use of a separate
namespace is described below.
The preprocess argument is a procedure of two
arguments: an S-expression and a namespace (section 9.3). The
preprocess procedure is applied to each expression read from the
source(s), and the provided namespace is where expressions are
expanded and compiled. The expression returned by preprocess is
expanded, compiled, and written to the output destination. The
default preprocess procedure returns its first argument.
To compile the input expressions, compile-file normally creates
a new namespace and copies all of the top-level bindings from the
current namespace into the new namespace (except for the bindings of
built-in-identifiers), without setting any variables as keywords (see
section 9.3.2). The 'use-current-namespace flag causes
the current namespace to be used for expansion and compilation,
instead.
By default, top-level require-library expressions are
recognized, and the specified library is loaded into the compilation
namespace. This causes library-based macros to be loaded for compiling
the file, but the require-library expression is still compiled
as an invocation of require-library. If the
'expand-require-library flag is specified, compile-file
instead replaces the call to require-library with the compiled
contents of the library if the specified library has not yet
been included during the call to compile-file.
All macros used in the source file must
either be defined at compile-time, defined using a top-level
define-macro statement in the source file (or in an
loaded or require-libraryed file that is expanded),
or defined locally in a let-macro expression.
Macros can be defined within the compiled file because
define-macro, define-id-macro,
and define-expansion-time forms are treated specially:
these forms are evaluated by compile-file after they are
compiled (in the special compilation namespace), so that the effect of
these expressions is visible while compiling the rest of the file. If
the 'ignore-macro-definitions flag is used, then all macros
used in the source file must be predefined or defined using
let-macro.
Next: Core: core.ss
Up: MzLib Libraries
Previous: Compatibility: compat.ss
PLT