#
Chapter 4
Compiling Collections with `mzc`

A collection is a group of files that conform to MzScheme's library collection system; see section 16 in PLT MzScheme: Language Manual for details. Every source file in a collection should contain a single `module` declaration.

The `--collection-zo` and `--collection-extension` flags direct `mzc` to compile a whole collection. The `--collection-zo` flag produces individual `.zo` files for each library in the collection. The `--collection-extension` flag produces a single `_loader` library for the collection.

The (sub-)collection to compile is specified on the command line for `mzc`. The specified collection must contain an `info.ss` library that provides information about how to compile the collection. (See section 7 for information on the format of `info.ss`.)

To compile a collection, `mzc` extracts `info.ss` information for the following fields:

- `name` -- the name of the collection as a string.

- `compile-omit-files` -- a list of library filenames (without paths); all Scheme files in the collection are compiled except for the files in this list. This information is optional.

- `compile-zo-omit-files` -- a list of library filenames that should not be compiled to byte code (but possibly to native code). This information is optional.

- `compile-extension-omit-files` -- a list of library filenames that should not be compiled to native code (but possibly to byte code). This information is optional.

- `compile-subcollections` -- a list of sub-collection sub-paths, where each sub-path is a list of strings; each full sub-collection path is formed by appending the sub-path to the path of the collection being compiled. Each sub-collection is compiled in the same way as the current collection, using the `info.ss` library of the sub-collection. This information is optional.

When compiling a collection to byte-code files, `mzc` automatically creates a `compiled` directory in the collection directory and puts `.zo` files there.

When compiling a collection to native code, `mzc` automatically created a `compiled` directory in the collection directory, a `native` directory in that `compiled` directory, and a platform-specific directory in `native` using the directory name returned by `system-library-subpath`. Intermediate `.c` and `.kp` files are kept in `native`. The platform-specific directory gets intermediate `.o`/`.obj` files and the final `_loader.so` or `_loader.dll`.

To compile a collection, `mzc` compiles only the library files that have changed since the last compilation. This form of dependency checking is usually too weak. For example, when a signature file changes, `mzc` does not automatically recompile all files that rely on the signatures. In this case, delete the `compiled` directory when a macro or signature file changes to ensure that the collection is compiled correctly.