On this page:
12.3.1 Bytecode Compilation
compile-zos
compile-collection-zos
compile-directory-zos
12.3.2 Loading Compiler Support
current-compiler-dynamic-require-wrapper
12.3.3 Options for the Compiler
somewhat-verbose
verbose
compile-subcollections
12.3.4 The Compiler as a Unit
12.3.4.1 Signatures
compiler^
compiler:  option^
12.3.4.2 Main Compiler Unit
compiler@
12.3.4.3 Options Unit
compiler:  option@

12.3 API for Raw Compilation

The compiler/compiler library provides the functionality of raco make for compilation to bytecode, but through a Racket API.

12.3.1 Bytecode Compilation

procedure

((compile-zos expr    
  [#:module? module?    
  #:verbose? verbose?])    
  racket-files    
  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.

procedure

(compile-collection-zos 
  collection ...+ 
  [#:skip-path skip-path 
  #:skip-doc-sources? skip-docs? 
  #:managed-compile-zo managed-compile-zo]) 
  void?
  collection : string?
  skip-path : (or/c path-string? #f) = #f
  skip-docs? : any/c = #f
  managed-compile-zo : (path-string? . -> . void?)
   = (make-caching-managed-compile-zo)
Compiles the specified collection’s files to ".zo" files by using managed-compile-zo on each source file. 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 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:

procedure

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

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.

parameter

(current-compiler-dynamic-require-wrapper)

  ((-> any) . -> . any)
(current-compiler-dynamic-require-wrapper proc)  void?
  proc : ((-> any) . -> . any)
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.

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

parameter

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

parameter

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

parameter

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

12.3.4 The Compiler as a Unit
12.3.4.1 Signatures

 (require compiler/sig)

signature

compiler^ : signature

Includes all of the names exported by compiler/compiler.

signature

compiler:option^ : signature

Includes all of the names exported by compiler/option.

12.3.4.2 Main Compiler Unit

 (require compiler/compiler-unit)

value

compiler@ : unit?

Provides the exports of compiler/compiler in unit form, where C-compiler operations are imports to the unit, although they are not used.

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

12.3.4.3 Options Unit

 (require compiler/option-unit)

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