1 Running mzc
2 Compiling Modified Modules to Bytecode
3 Creating and Distributing Stand-Alone Executables
4 Packaging Library Collections
5 Compiling and Linking C Extensions
6 Embedding Scheme Modules via C
7 Compiling to Raw Bytecode
8 Compiling to Native Code via C
9 Scheme API for Compilation
Index
On this page:
2.1 Bytecode Files
2.2 Dependency Files
2.3 Scheme Compilation Manager API
make-compilation-manager-load/ use-compiled-handler
managed-compile-zo
trust-existing-zos
make-caching-managed-compile-zo
manager-compile-notify-handler
manager-trace-handler
2.4 Compilation Manager Hook for Syntax Transformers
register-external-file
Version: 4.0.1

 

2 Compiling Modified Modules to Bytecode

The default mode for mzc is to accept filenames for Scheme modules to be compiled to bytecode format. Modules are re-compiled only if the source Scheme file is newer than the bytecode file, or if any imported module is recompiled.

2.1 Bytecode Files

A file "⟨name⟩.⟨ext⟩" is compiled to bytecode that is saved as "compiled/⟨name⟩_⟨ext⟩.zo" relative to the file. As a result, the bytecode file is normally used automatically when "⟨name⟩.⟨ext⟩" is required as a module, since the underlying load/use-compiled operation detects such a bytecode file.

For example, in a directory that contains the following files:

then

  mzc a.scm

triggers the creation of "compiled/a_ss.zo", "compiled/b_ss.zo", and "compiled/c_ss.zo". A subsequent

  mzscheme a.scm

loads bytecode from the generated ".zo" files, paying attention to the ".scm" sources only to confirm that each ".zo" file has a later timestamp.

In contrast,

  mzc b.scm c.scm

would create only "compiled/b_scm.zo" and "compiled/c_scm.zo", since neither "b.scm" nor "c.scm" imports "a.scm".

2.2 Dependency Files

In addition to a bytecode file, mzc creates a file "compiled/⟨name⟩_⟨ext⟩.dep" that records dependencies of the compiled module on other module files. Using this dependency information, a re-compilation request via mzc can consult both the source file’s timestamp and the timestamps for the sources and bytecode of imported modules. Furthermore, imported modules are themselves compiled as necessary, including updating the bytecode and dependency files for the imported modules, transitively.

Continuing the mzc a.scm example from the previous section, the mzc creates "compiled/a_scm.dep", "compiled/b_scm.dep", and "compiled/c_scm.dep" at the same time as the ".zo" files. The "compiled/a_scm.dep" file records the dependency of "a.scm" on "b.scm", "c.scm" and the scheme library. If the "b.scm" file is modified (so that its timestamp changes), then running

  mzc a.scm

again rebuilds "compiled/a_ss.zo" and "compiled/b_ss.zo".

For module files that are within library collections, setup-plt uses the same ".zo" and ".dep" conventions and files as mzc, so the two tools can be used together.

2.3 Scheme Compilation Manager API

 (require compiler/cm)

The compiler/cm module implements the compilation and dependency management used by mzc and setup-plt.

(make-compilation-manager-load/use-compiled-handler)

  (path? (or/c symbol? false/c) . -> . any)

Returns a procedure suitable as a value for the current-load/use-compiled parameter. The returned procedure passes it arguments on to the current-load/use-compiled procedure that is installed when make-compilation-manager-load/use-compiled-handler is called, but first it automatically compiles a source file to a ".zo" file if

After the handler procedure compiles a ".zo" file, it creates a corresponding ".dep" file that lists the current version, plus the ".zo" timestamp for every file that is required by the module in the compiled file. Additional dependencies can be installed during compilation via compiler/cm-accomplice.

The handler caches timestamps when it checks ".dep" files, and the cache is maintained across calls to the same handler. The cache is not consulted to compare the immediate source file to its ".zo" file, which means that the caching behavior is consistent with the caching of the default module name resolver (see current-module-name-resolver).

If use-compiled-file-paths contains an empty list when make-compilation-manager-load/use-compiled-handler is called, then exn:fail:contract exception is raised.

Do not install the result of make-compilation-manager-load/use-compiled-handler when the current namespace contains already-loaded versions of modules that may need to be recompiled – unless the already-loaded modules are never referenced by not-yet-loaded modules. References to already-loaded modules may produce compiled files with inconsistent timestamps and/or ".dep" files with incorrect information.

(managed-compile-zo file [read-src-syntax])  void?

  file : path-string?

  

read-src-syntax

 

:

 

(any/c input-port? . -> . syntax?)

 

 

 

=

 

read-syntax

Compiles the given module source file to a ".zo", installing a compilation-manager handler while the file is compiled (so that required modules are also compiled), and creating a ".dep" file to record the timestamps of immediate files used to compile the source (i.e., files required in the source).

If file is compiled from source, then read-src-syntax is used in the same way as read-syntax to read the source module. The normal read-syntax is used for any required files, however.

(trust-existing-zos)  boolean?

(trust-existing-zos trust?)  void?

  trust? : any/c

A parameter that is intended for use by setup-plt when installing with pre-built ".zo" files. It causes a compilation-manager load/use-compiled handler to “touch” out-of-date ".zo" files instead of re-compiling from source.

(make-caching-managed-compile-zo read-src-syntax)

  (path-string? . -> . void?)

  read-src-syntax : (any/c input-port? . -> . syntax?)

Returns a procedure that behaves like managed-compile-zo (providing the same read-src-syntax each time), but a cache of timestamp information is preserved across calls to the procedure.

(manager-compile-notify-handler)  (path? . -> . any)

(manager-compile-notify-handler notify)  void?

  notify : (path? . -> . any)

A parameter for a procedure of one argument that is called whenever a compilation starts. The argument to the procedure is the file’s path.

(manager-trace-handler)  (string? . -> . any)

(manager-trace-handler notify)  void?

  notify : (string? . -> . any)

A parameter for a procedure of one argument that is called to report compilation-manager actions, such as checking a file. The argument to the procedure is a string.

2.4 Compilation Manager Hook for Syntax Transformers

 (require compiler/cm-accomplice)

(register-external-file file)  void?

  file : (and path? complete-path?)

Registers the complete path file with a compilation manager implemented by compiler/cm, if one is active. The compilation manager then records (in a ".dep" file) the path as contributing to the implementation of the module currently being compiled. Afterward, if the registered file is modified, the compilation manager will know to recompile the module.

The include macro, for example, calls this procedure with the path of an included file as it expands an include form.