12.3 API for Raw Compilation

12.3.1 Bytecode Compilation

The compiler takes a list of Racket 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.

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

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

12.3.3 Options for the Compiler

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.

12.3.4 The Compiler as a Unit

12.3.4.1 Signatures

12.3.4.2 Main Compiler Unit

The unit imports compiler:option^, dynext:compile^, dynext:link^, and dynext:file^. It exports compiler^.

12.3.4.3 Options Unit