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 collection ) loads a library from library-file in the collection named by the first collection, where both library-file 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 file collection ) requires file 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 file.

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
               \>"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.

When the value of the require-library-use-compiled Boolean parameter (see section 9.4.1.8) is #t, require-library loads library files using load/use-compiled; otherwise load is used. 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.

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

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

PLT