Compiling Files

Files: compile.ss, compileu.ss, compiler.ss, compiles.ss, compilec.ss
Signature: mzlib:compile^
Unit: mzlib:compile@

(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 recusively 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-libarary is described below.
• 'preserve-elaborations -- instead of evaluting the expressions within a 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.
• 'also-preserve-elaborations -- like 'preserve-elaborations, but the expressions in a begin-elaboration-time form are also eveluated 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 eveluated 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 aargument.

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 constants (see section 9.3.2) or keywords (see section 9.3.3). 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.