On this page:
9.4.1 Bytecode Compilation
9.4.2 Compilation via C
9.4.3 Loading compiler support
9.4.4 Options for the Compiler
vehicles: monoliths
9.4.5 The Compiler as a Unit Signatures
compiler: option^
compiler: inner^
compile-c-extension Main Compiler Unit
[email protected] Options Unit
compiler: [email protected] Compiler Inner Unit
[email protected]

9.4 API for Raw Compilation

The compiler/compiler library provides the functionality of mzc for compilation to bytecode and via C, but through a Racket API.

9.4.1 Bytecode Compilation

((compile-zos expr    
  [#:module? module?    
  #:verbose? verbose?])    
  dest-dir)  void?
  expr : any/c
  module? : any/c = #f
  verbose? : any/c = #f
  racket-files : (listof path-string?)
  dest-dir : (or/c path-string? false/c (one-of/c 'auto))
Supplying just expr returns a compiler that is initialized with the expression expr, as described below.

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.

(compile-collection-zos collection    
  [#:skip-path skip-path    
  #:skip-doc-sources? skip-docs?])  void?
  collection : string?
  skip-path : (or/c path-string? #f) = #f
  skip-docs? : any/c = #f
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 racket-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:

The compilation process for an individual file is driven by managed-compile-zo from compiler/cm.

(compile-directory-zos path    
  [#:verbose verbose?    
  #:skip-path skip-path    
  #:skip-doc-sources? skip-docs?])  void?
  path : path-string?
  info : ()
  verbose? : any/c = #f
  skip-path : (or/c path-string? #f) = #f
  skip-docs? : any/c = #f
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.

9.4.2 Compilation via C

((compile-extensions expr)    
  dest-dir)  void?
  expr : any/c
  racket-files : (listof path-string?)
  dest-dir : (or/c path-string? false/c (one-of/c 'auto))
Like compile-zos, but the racket-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.

((compile-extensions-to-c expr)    
  dest-dir)  void?
  expr : any/c
  racket-files : (listof path-string?)
  dest-dir : (or/c path-string? false/c (one-of/c 'auto))
Like compile-extensions, but only ".c" files are produced, not extensions.

(compile-c-extensions c-files dest-dir)  void?
  c-files : (listof path-string?)
  dest-dir : (or/c path-string? false/c (one-of/c 'auto))
Compiles each ".c" file (usually produced with compile-extensions-to-c) in c-files to an extension. The dest-dir argument is handled as in compile-extensions.

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

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

(somewhat-verbose)  boolean?
(somewhat-verbose on?)  void?
  on? : any/c
A #t value for the parameter causes the compiler to print the files that it compiles and produces. The default is #f.

(verbose)  boolean?
(verbose on?)  void?
  on? : any/c
A #t value for the parameter causes the compiler to print verbose messages about its operations. The default is #f.

(setup-prefix)  string?
(setup-prefix str)  void?
  str : string?
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.

(compile-subcollections)  (one-of/c #t #f)
(compile-subcollections cols)  void?
  cols : (one-of/c #t #f)
A parameter that specifies whether sub-collections are compiled by compile-collection-zos. The default is #t.

(compile-for-embedded)  boolean?
(compile-for-embedded embed?)  void?
  embed? : any/c
A #t values for this parameter creates ".c" files and object files to be linked directly with an embedded Racket run-time system, instead of ".c" files and object files to be dynamically loaded into Racket as an extension. The default is #f.

(propagate-constants)  boolean?
(propagate-constants prop?)  void?
  prop? : any/c
A parameter to control the compiler’s constant propagating when compiling via C. The default is #t.

(assume-primitives)  boolean?
(assume-primitives assume?)  void?
  assume? : any/c
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.

(stupid)  boolean?
(stupid allow?)  void?
  allow? : any/c
A parameter that allow obvious non-syntactic errors, such as ((lambda () 0) 1 2 3), when compiling via C. The default is #f.

(vehicles)  symbol?
(vehicles mode)  void?
  mode : symbol?
A parameter that controls how closures are compiled via C. The possible values are:

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 Racket expressions crammed into one C function when compiling via C. The default is 25.

(unpack-environments)  boolean?
(unpack-environments unpack?)  void?
  unpack? : any/c
Setting this parameter to #f might help compilation via C for register-poor architectures. The default is #t.

(debug)  boolean?
(debug on?)  void?
  on? : any/c
A #t creates a "debug.txt" debugging file when compiling via C. The default is #f.

(test)  boolean?
(test on?)  void?
  on? : any/c
A #t value for this parameter causes compilation via C to ignore top-level expressions with syntax errors. The default is #f.

9.4.5 The Compiler as a Unit Signatures

 (require compiler/sig)

compiler^ : signature
Includes all of the names exported by compiler/compiler.

compiler:option^ : signature
Includes all of the names exported by compiler/option.

compiler:inner^ : signature
The high-level compiler/compiler interface relies on a low-level implementation of the extension compiler, which is available from compiler/comp-unit as implementing the compiler:inner^ signature.

(eval-compile-prefix expr)  void?
  expr : any/c
Evaluates expr. Future calls to compile-extension or compile-extension-to-c see the effects of the evaluation.

(compile-extension racket-source dest-dir)  void?
  racket-source : path-string?
  dest-dir : path-string?
Compiles a single Racket file to an extension.

(compile-extension-to-c racket-source    
  dest-dir)  void?
  racket-source : path-string?
  dest-dir : path-string?
Compiles a single Racket file to a ".c" file.

(compile-c-extension c-source dest-dir)  void?
  c-source : path-string?
  dest-dir : path-string?
Compiles a single ".c" file to an extension. Main Compiler Unit

 (require compiler/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^. Options Unit

 (require compiler/option-unit)

Provides the exports of compiler/option in unit form. It imports no signatures, and exports compiler:option^. Compiler Inner Unit

 (require compiler/comp-unit)