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 symbol specifies a requested field, i.e., the kind of information is requested. If the requested information is available, then the info.ss procedure returns that information; otherwise, it must call the failure thunk.

For example, the following procedure is in the info.ss library of the help collection:

  (lambda (request failure-thunk)
    (case request
      [(name) "Help"]
      [(compile-prefix) `(begin
                           (require-library "sig.ss" "mred")
                           (require-library "sig.ss" "help"))]
      [(compile-omit-files) (list "sig.ss" "manuals.ss")]
      [(compile-elaboration-zos) (list "sig.ss")]
      [(mred-launcher-libraries) (list "help.ss")]
      [(mred-launcher-names) (list "Help Desk")]
      [else (failure-thunk)]))

The info.ss system is standardized by convention. A collection's info.ss file can be used by several clients (including mzc, Setup PLT, and Help Desk), each requesting a different set of fields.

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

• '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 .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.

• Macro and Elaboration-Time Libraries