Compiling Files: compile.ss

Next: Core: core.ss Up: MzLib Libraries Previous: Compatibility: compat.ss

## Compiling Files: `compile.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 `load`ed or `require-library`ed 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