Chapter 6

cm.ss: Compilation Manager

To load: (require (lib "cm.ss"))

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

Returns a procedure suitable as a value for the current-load/use-compiled parameter (see section 7.9.1.6 in PLT MzScheme: Language Manual). The returned procedure passes it arguments on to the current current-load/use-compiled procedure (i.e., the one installed when this procedure is called), but first it automatically compiles source files to a .zo file if

• the file is expected to contain a module (i.e., the second argument to the handler is a symbol);

• the value of each of current-eval, current-load, and current-namespace is the same as when make-compilation-manager-load/use-compiled-handler was called;

• the value of use-compiled-file-paths contains the first path that was present when make-compilation-manager-load/use-compiled-handler was called;

• the value of current-load/use-compiled is the result of this procedure; and

• one of the following holds:

  • the source file is newer than the .zo file in the first sub-directory listed in use-compiled-file-paths (at the time that make-compilation-manager-load/use-compiled-handler was called)

  • no .dep file exists next to the .zo file;

  • the version recorded in the .dep file does not match the result of (version);

  • one of the files listed in the .dep file has a .zo timestamp newer than the one recorded in the .dep file.

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 (including require-for-syntaxes and require-for-templates).

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 section 5.4 in PLT MzScheme: Language Manual).

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)      PROCEDURE

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, including require-for-syntaxes and require-for-templates).

(trust-existing-zos on? [procedure])      

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)      PROCEDURE

Returns a procedure that behaves like managed-compile-zo, but a cache of timestamp information is preserved across calls to the procedure.

(manager-compile-notify-handler [notify-proc])      PROCEDURE

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 [notify-proc])      PROCEDURE

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.