8.4 API for Raw Compilation
The
compiler/compiler library provides the
functionality of
mzc for compilation to bytecode and via C, but
through a Scheme API.
8.4.1 Bytecode Compilation
Supplying just expr returns a compiler that is initialized
with the expression expr, as described below.
The compiler takes a list of Scheme files and compiles each of them to
bytecode, placing the resulting bytecode in a ".zo" file
within the directory specified by dest-dir. If
dest-dir is #f, each bytecode result is placed in
the same directory as its source file. If dest-dir is
'auto, each bytecode file is placed in a "compiled"
subdirectory relative to the source; the directory is created if
necessary.
If expr is anything other than #f, then a namespace
is created for compiling the files that are supplied later, and
expr is evaluated to initialize the created namespace. For
example, expr might load a set of macros. In addition, the
expansion-time part of each expression later compiled is evaluated in
the namespace before being compiled, so that the effects are visible
when compiling later expressions.
If expr is #f, then no compilation namespace is
created (the current namespace is used), and expressions in the files
are assumed to compile independently (so there’s no need to evaluate
the expansion-time part of an expression to compile).
Typically, expr is #f for compiling module
files, and it is (void) for compiling files with top-level
definitions and expressions.
If module? is #t, then the given files are read and
compiled as modules (so there is no dependency on the current
namespace’s top-level environment).
If verbose? is #t, the output file for each given
file is reported through the current output port.
Compiles the specified collection’s files to
".zo" files.
The
".zo" files are placed into the collection’s
"compiled" directory. By default, all files with the
extension
".rkt",
".ss", or
".scm" in a collection are
compiled, as are all such files within subdirectories, execept that
any file or directory whose path starts with
scheme-path is
skipped. (“Starts with” means that the simplified path
p’s
byte-string form after
(simplify-path p #f)starts with the
byte-string form of
(simplify-path skip-path #f).)
The collection compiler reads the collection’s "info.rkt" file
(see "info.rkt" File Format) to obtain further instructions for compiling the
collection. The following fields are used:
name : The name of the collection as a string, used
only for status and error reporting.
compile-omit-paths : A list of immediate file
and directory paths that should not be compiled. Alternatively,
this field’s value 'all, which is equivalent to
specifying all files and directories in the collection (to
effectively ignore the collection for
compilation). Automatically omitted files and directories are
"compiled", "doc", and those whose names
start with ..
Files that are required by other files, however, are always
compiled in the process of compiling the requiring file – even
when the required file is listed with this field or when the
field’s value is 'all.
compile-omit-files : A list of filenames (without
directory paths); that are not compiled, in addition to the
contents of compile-omit-paths. Do not use this
field; it is for backward compatibility.
scribblings : A list of pairs, each of which
starts with a path for documentation source. The sources (and
the files that they require) are compiled in the same way as
".rkt", ".ss", and ".scm" files,
unless the provided skip-docs? argument is a true
value.
The compilation process for an individual file is driven by
managed-compile-zo from compiler/cm.
Like
compile-collection-zos, but compiles the given directory
rather than a collection. The
info function behaves like the
result of
get-info to supply
"info.rkt" fields,
instead of using an
"info.rkt" file (if any) in the directory.
8.4.2 Compilation via C
Like
compile-zos, but the
scheme-files are compiled
to native-code extensions via C. If
dest-dir is
'auto, each extension file (
".dll",
".so",
or
".dylib") is placed in a subdirectory relative to the
source produced by
(build-path "compiled" "native" (system-library-subpath)); the directory is created if necessary.
8.4.3 Loading compiler support
The compiler unit loads certain tools on demand via dynamic-require
and get-info. If the namespace used during compilation is different
from the namespace used to load the compiler, or if other load-related
parameters are set, then the following parameter can be used to
restore settings for dynamic-require.
A parameter whose value is a procedure that takes a thunk to
apply. The default wrapper sets the current namespace (via
parameterize) before calling the thunk, using the namespace
in which the
compiler/compiler library was originally
instantiated.
8.4.4 Options for the Compiler
The
compiler/option module provides options (in the
form of parameters) that control the compiler’s behaviors.
More options are defined by the dynext/compile and
dynext/link libraries, which control the actual C
compiler and linker that are used for compilation via C.
A #t value for the parameter causes the compiler to print
the files that it compiles and produces. The default is #f.
A #t value for the parameter causes the compiler to print
verbose messages about its operations. The default is #f.
A parameter that specifies a string to embed in public function names
when compiling via C. This is used mainly for compiling extensions
with the collection name so that cross-extension conflicts are less
likely in architectures that expose the public names of loaded
extensions. The default is "".
A #f value for the parameter keeps intermediate ".c"
and ".o" files generated during compilation via C. The
default is #t.
A #t values for this parameter creates ".c" files
and object files to be linked directly with an embedded PLT Scheme
run-time system, instead of ".c" files and object files to be
dynamically loaded into PLT Scheme as an extension. The default is
#f.
A parameter to control the compiler’s constant propagating when
compiling via C. The default is #t.
A
#t parameter value effectively adds
(require mzscheme) to the beginning of the program. This parameter is useful
only when compiling non-
module code. The default is
#f.
A parameter that allow obvious non-syntactic errors, such as
((lambda () 0) 1 2 3), when compiling via C. The default is
#f.
A parameter that controls how closures are compiled via C. The
possible values are:
'vehicles:automatic : automatic grouping
'vehicles:functions : groups within a procedure
'vehicles:monolithic : groups randomly
A parameter that determines the number of random
groups for 'vehicles:monolithic mode.
Sets the randomizer seed for 'vehicles:monolithic mode.
A parameter that determines the number of top-level Scheme expressions
crammed into one C function when compiling via C. The default is
25.
Setting this parameter to #f might help compilation via C
for register-poor architectures. The default is #t.
A #t creates a "debug.txt" debugging file when
compiling via C. The default is #f.
A #t value for this parameter causes compilation via C to
ignore top-level expressions with syntax errors. The default is
#f.
8.4.5 The Compiler as a Unit
8.4.5.1 Signatures
Compiles a single Scheme file to an extension.
Compiles a single Scheme file to a ".c" file.
Compiles a single ".c" file to an extension.
8.4.5.2 Main Compiler Unit
Provides the exports of
compiler/compiler in unit
form, where C-compiler operations are imports to the unit.
The unit imports compiler:option^, dynext:compile^,
dynext:link^, and dynext:file^. It exports
compiler^.
8.4.5.3 Options Unit
8.4.5.4 Compiler Inner Unit