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.