Next: MzLib Overview Up: PLT MzScheme: Language Manual Previous: Saving and Restoring Program

Library Collections and MzLib

A library is a fragment of MzScheme code that can be used in multiple programs. MzScheme provides an mechanism for grouping libraries into collections that can be 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 the library name along with the name of the library's collection: (require-library library-file-path collection ) loads a library from 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 loaded from the mzlib collection. The require-library form returns the result(s) of the last expression in the library file.

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.

When require-library is used to load a file, the library name and the resulting value(s) are recored in a table associated with the current namespace. If require-library is evaluated for a library that is already registered in the current namespace's load table, then the library is not loaded again; the result(s) recorded in the load table is returned, instead.

While require-library loads a library file, it sets the current-require-relative-collection parameter to the path of collection names that specify the library's subcollection. This path is used by the require-relative-library form: (require-relative-library library-file-path collection ) requires library-file-path from the collection specified by the current-require-relative-collection parameter; if extra collections are provided, they are appended to the end of the subcollection path in current-require-relative-collection for finding library-file-path.

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 9.4.1.8). The list of paths in current-library-collection-paths is searched from first to last to locate a collection when a library is requested. The value of the 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")
                     "/usr/local/lib/plt/collects" ; Unix only
                     "/boot/apps/plt/collects" ; BeOS only
                     "c:\\plt\\collects")) ; Windows only
        null)))

where program is the name used to start MzScheme (always a complete path for MacOS). See also section 11.2.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.

The require-library form loads library files using load/use-compiled. In the table of loaded libraries, library names are registered using the original suffix even when load/use-compiled loads a compiled version of a file.

Since require-library's libraries and collections are specified via string literals, this form supports the static analysis of programs by MrSpidey, DrScheme's static debugger. The require-library/proc procedure generalizes require-library to a procedural form, but it is not supported by the static debugger. Nevertheless, the require-library form normally expands to an application of require-library/proc:

  (require-library library collection   ) 
    
  (require-library/proc library collection   )

Similarly, require-relative-library/proc is the procedure form of require-relative-library.

The provide-library procedure installs values lazily into the current namespace's table of library values, if no values are yet registered for the specified library. (provide-library thunk library-file-path collection ) installs thunk as the value-generator for library-file-path within the collection specified by the collection strings (defaulting to "mzlib" if no collection is provided). A #f return value indicates that the library already has values in the table, and thunk is ignored. Otherwise, the result is #t, and when the library is later requested via require-library, thunk is called to obtain the library's value(s). The thunk procedure is called only the first time that the library is requested, and then the returned values replace thunk in the namespace's table.

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 section 15.1.

Next: MzLib Overview Up: PLT MzScheme: Language Manual Previous: Saving and Restoring Program

PLT