Chapter 16

Library Collections and MzLib

A library is module declaration for use by multiple programs. MzScheme provides a mechanism for grouping libraries into collections that can be easily distributed and easily added to a local MzScheme installation. A collection is normally installed into a directory named collects that is in the same directory as the MzScheme executable.³⁸ Each installed collection is represented as a subdirectory within the collects directory.

Client programs incorporate a library by using a module path of the form (lib library-file-path collection ···). Such a path accesses the module in the file library-file-path in the collection named by the first collection, where both library-file-path and collection are literal strings that will be used as elements in a pathname. If additional collection strings are provided, they are used to form a path into a subcollection. If the collection arguments are omitted, the library is accessed in the mzlib collection.

The info.ss library in a collection is special by convention. This library is used to provide information about the collection to mzc (the MzScheme compiler) or MrEd. For more information see PLT mzc: MzScheme Compiler Manual and PLT MrEd: Graphical Toolbox Manual.

There is usually one standard collects directory, but MzScheme supports any number of directories containing collections. The search path for collections is determined by the current-library-collection-paths parameter (see section 7.4.1.6). The list of paths in current-library-collection-paths is searched from first to last to locate a collection. To find a sub-collection, the enclosing collection is first found; if the sub-collection is not present in the found enclosing collection, then the search continues by looking for another instance of the enclosing collection, and so on. In other words, the directory tree for each element in the search path is spliced together with the directory trees of other path elements. (The ``splicing'' of tress applies only to directories; a file within a collection is found only within the first instance of the collection.)

The value of the current-library-collection-paths parameter is initialized by the stand-alone version of MzScheme as follows:³⁹

(current-library-collection-paths 
 (path-list-string->path-list 
  (or (getenv "PLTCOLLECTS") "") 
  (or (ormap (lambda (p) (and p (directory-exists? p) (list p))) 
             (list (let ([v (getenv "PLTHOME")]) 
                     (and v (build-path v "collects"))) 
                   (find-executable-path program "collects") 
                   (find-executable-path program (build-path 'up "collects")) 
                   (find-executable-path program (build-path 'up 'up "collects")))) 
      null))) 

where program is the name used to start MzScheme (always a complete path for Mac OS Classic). See also section 11.3.1 for information about path-list-string->path-list and find-executable-path. (collection-path collection ···¹) returns the path containing the libraries of collection; if the collection is not found, the exn:i/o:filesystem exception is raised.

MzScheme is distributed with a standard collection of utility libraries with MzLib as the representative library. The name of this collection is mzlib, so the libraries are distributed in a mzlib subdirectory of the collects library collection directory. MzLib is described in PLT MzLib: Libraries Manual.