16.2 Libraries and Collections
A library is module declaration for use by multiple programs. Scheme further groups libraries into collections that can be easily distributed and easily added to a local MzScheme installation.
Some collections are distributed via PLaneT. Such collections are referenced through a planet module path (see require) and are downloaded by Scheme on demand.
Other collections are distributed with PLT Scheme, in which case each collection is a directory that is located in a "collects" directory relative to the mzscheme. A collection can also be installed in a user-specific directory. More generally, the search path for installed collections can be configured through the current-library-collection-paths parameter. In all of these cases, the collections are referenced through lib paths (see require).
For example, the following module uses the "getinfo.ss" library module from the "setup" collection, and the "cards.ss" library module from the "games" collection’s "cards" subcollection:
(lib "games/cards/cards.ss")) |
.... |
In general, the rel-string in (lib rel-string) consists of one or more path elements that name collections, and then a final path element that names a library file; the path elements are separated by /. If the final element has no file suffix, then /main.ss is implicitly appended to the path.
The translation of a "planet" or "lib" path to a module declaration is determined by the module name resolver, as specified by the current-module-name-resolver parameter.
For the default module name resolver, The search path for collections is determined by the current-library-collection-paths parameter. The list of paths in current-library-collection-paths is searched from first to last to locate the first collection in a rel-string. 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 in mzscheme to the result of (find-library-collection-paths).
(find-library-collection-paths [extras]) → (listof path?) |
extras : (listof path-string?) = null |
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.
Extra directories provided in extras are included next, converted to complete paths 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. If it is not defined, the default collection path list (as constructed by the first three bullets above) is used directly.
(collection-path collection ) → path? |
collection : string? |
Returns the path to a directory containing the libraries of the collection indicated by collections, where the second collection (if any) names a sub-collection, and so on. If the collection is not found, the exn:fail:filesystem exception is raised.
→ (listof (and/c path? complete-path?)) |
(current-library-collection-paths paths) → void? |
paths : (listof (and/c path? complete-path?)) |
Parameter that determines a list of complete directory paths for library collections used by require. See Libraries and Collections for more information.
(use-user-specific-search-paths on?) → void? |
on? : any/c |
Parameter that determines whether user-specific paths, which are in the directory produced by (find-system-path 'addon-dir), are included in search paths for collections and other files. For example, find-library-collection-paths omits the user-specific collection directory when this parameter’s value is #f.