Compiling Collections with mzc

A collection is a group of files that conform to MzScheme's library collection system; see library collections in PLT MzScheme: Language Manual for details.

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. The result of loading the info.ss library must be a procedure that takes two arguments: a symbol and a failure thunk. The thunk is called to obtain information about the collection, and the symbol specifies what kind of information is requested. If the information specified by the symbol is available, the thunk returns the information, otherwise it calls the failure thunk. This method of obtaining information about a collection is standardized by convention, so the info.ss file can be used by multiple clients (including mzc and MrEd).

To compile a collection mzc requests the following information from info.ss.

• 'name -- the name of the collection as a string.
• 'compile-prefix -- an S-expression to use as the elaboration-time prefix expression for compiling all files in the collection. This information is optional (i.e., the failure thunk can be called when this symbol is provided to the info.ss procedure), but it is recommended beacuse it indicates to external tools that the collection can be compiled. (Use '(void) if no prefix is needed.)
• '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. If a library contains elaboration time expressions (e.g., macros or signatures) that are not local to the file, then the library file should be included 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 the .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 or .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 currently know to re-compile 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.

• Macro and Elaboration-Time Libraries