On this page:
find-library-collection-paths
collection-file-path
collection-path
current-library-collection-paths
use-user-specific-search-paths

17.2 Libraries and Collections

A library is module declaration for use by multiple programs. Racket further groups libraries into collections that can be easily distributed and easily added to a local Racket installation.

Some collections are distributed via PLaneT. Such collections are referenced through a planet module path (see require) and are downloaded by Racket on demand.

Other collections are distributed with Racket, in which case each collection is a directory that is located in a "collects" directory relative to the Racket executable. 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.rkt" library module from the "setup" collection, and the "cards.rkt" library module from the "games" collection’s "cards" subcollection:

  #lang racket
  (require (lib "setup/getinfo.rkt")
           (lib "games/cards/cards.rkt"))
  ....

This example is more compactly and more commonly written as

  #lang racket
  (require setup/getinfo
           games/cards/cards)
  ....

When an identifier id is used in a require form, it is converted to (lib rel-string) where rel-string is the string form of id.

A 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 rel-string contains no /s, then then /main.rkt is implicitly appended to the path. If rel-string contains / but does not end with a file suffix, then .rkt 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 that contains rel-string. In other words, the filesystem tree for each element in the search path is spliced together with the filesystem trees of other path elements. Some Racket tools rely on unique resolution of module path names, so an installation and current-library-collection-paths configuration should not allow multiple files to match the same collection and file name.

The value of the current-library-collection-paths parameter is initialized in the Racket executable to the result of (find-library-collection-paths).

(find-library-collection-paths [pre-extras    
  post-extras])  (listof path?)
  pre-extras : (listof path-string?) = null
  post-extras : (listof path-string?) = null
Produces a list of paths as follows:

(collection-file-path file collection ...+)  path?
  file : path-string?
  collection : path-string?
Returns the path to the file indicated by file in the collection specified by the collections, where the second collection (if any) names a sub-collection, and so on. If file is not found, but file ends in ".rkt" and a file with the suffix ".ss" exists, then the directory of the ".ss" file is used. If file is not found and the ".rkt"/".ss" conversion does not apply, but a directory corresponding to the collections is found, then a path using the first such directory is returned. Finally, if the collection is not found, the exn:fail:filesystem exception is raised.

(collection-path collection ...+)  path?
  collection : path-string?
Like collection-file-path, but without a specified file name, so that the first directory indicated by collections is returned. The collection-file-path function normally should be used, instead, to support splicing of library-collection trees at the file level.

Parameter that determines a list of complete directory paths for library collections used by require. See Libraries and Collections for more information.

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.