#
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.54 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 `···`)`. For example, the following module uses the `match.ss` library module from the default `mzlib` collection, the `getinfo.ss` library module from the `setup` collection, and the `cards.ss` library module from the `games` collection's `cards` subcollection:

    (module my-game mzscheme
      (require (lib "match.ss")
               (lib "getinfo.ss" "setup")
               (lib "cards.ss" "games" "cards"))
      ....)

In general,`(`lib` library-file-path collection `···`)` 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 path. 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.9.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 to the result of `(find-library-collection-paths``)`.55 The `find-library-collection-paths` procedure produces a list of paths as follows:

- The path produced by `(`build-path` (`find-system-path` 'addon-dir) (`version`) "collects")` is the first element of the default collection path list, unless the value of the `use-user-specific-search-paths` parameter is `#f`.

- If the executable embeds a list of search paths, they are included (in order) after the first element in the default collection path list. Embedded relative paths are included only when the corresponding directory exists relative to the executable.

- If the directory specified by `(`find-system-path` 'collects-dir)` is absolute, or if it is relative (to the executable) and it exists, then it is added to the end of the default collection path list.

- If the `PLTCOLLECTS` environment variable is defined, it is combined with the default list using `path-list-string->path-list` (see section 11.3.2). If it is not defined, the default collection path list (as constructed by the first three bullets above) is used directly.

The path produced by `(`find-system-path` 'collects-dir)` is normally embedded in an executable; in stand-alone MzScheme (or MrEd), it can be overridden via a `--collects` or `-X` command-line flag.

`(collection-path``` `collection``` `···`1`)` returns the path containing the libraries of `collection`; if the collection is not found, the `exn:fail: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.

54 In the PLT distribution of MzScheme for Unix, the `collects` directory is in the top-level `plt` directory, rather than with the platform-specific binary in `plt/bin`.

55 MrEd initializes the ``current-library-collection-paths`` parameter in the same way.