#
Chapter 7
`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 function 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 function; 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 `require`d by the module in the compiled file (including `require-for-syntax`es and `require-for-template`s).

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 `require`d in the source, including `require-for-syntax`es and `require-for-template`s).

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