From 1f48fb2c1086472673bcb510f835cd4b2fcff9c5 Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Thu, 26 Jul 2007 19:34:26 +0000 Subject: [PATCH] add information on collects to new reference svn: r6973 --- collects/scribblings/reference/collects.scrbl | 118 ++++++++++++++++++ .../scribblings/reference/filesystem.scrbl | 4 +- .../scribblings/reference/reference.scrbl | 1 + collects/scribblings/reference/running.scrbl | 8 ++ collects/scribblings/reference/syntax.scrbl | 3 +- 5 files changed, 131 insertions(+), 3 deletions(-) create mode 100644 collects/scribblings/reference/collects.scrbl create mode 100644 collects/scribblings/reference/running.scrbl diff --git a/collects/scribblings/reference/collects.scrbl b/collects/scribblings/reference/collects.scrbl new file mode 100644 index 0000000000..4777c995f5 --- /dev/null +++ b/collects/scribblings/reference/collects.scrbl @@ -0,0 +1,118 @@ +#reader(lib "docreader.ss" "scribble") +@require["mz.ss"] + +@title[#:tag "mz:collects"]{Libraries and Collections} + +A @deftech{library} is @scheme[module] declaration for use by multiple +programs. Scheme further groups libraries into @deftech{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 @scheme[planet] module path (see +@scheme[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 @file{collects} +directory relative to the @exec{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 +@scheme[current-library-collection-paths] parameter. In all of these +cases, the collections are referenced through @scheme[lib] paths (see +@scheme[require]). + +For example, the following module uses the @file{match.ss} library module +from the default @file{mzlib} collection, the @file{getinfo.ss} +library module from the @file{setup} collection, and the +@file{cards.ss} library module from the @file{games} collection's +@file{cards} subcollection: + +@schemeblock[ +(module my-game mzscheme + (require (lib "mzlib/match.ss") + (lib "setup/getinfo.ss" "setup") + (lib "games/cards/cards.ss")) + ....) +] + +In general, the @scheme[_rel-string] in @scheme[(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 @litchar{/}. + +The translation of a @scheme{planet} or @scheme{lib} path to a +@scheme[module] declaration is determined by the @tech{module name +resolver}, as specified by the @scheme[current-module-name-resolver] +parameter. + +For the default @tech{module name resolver}, The search path for +collections is determined by the +@scheme[current-library-collection-paths] parameter. The list of paths +in @scheme[current-library-collection-paths] is searched from first to +last to locate the first collection in a @scheme[_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 @scheme[current-library-collection-paths] parameter +is initialized in @exec{mzscheme} to the result of +@scheme[(find-library-collection-paths)]. + + +@defproc[(find-library-collection-paths) (listof path?)]{ + +Produces a list of paths as follows: + +@itemize{ + +@item{The path produced by @scheme[(build-path (find-system-path + 'addon-dir) (version) "collects")] is the first element of the + default collection path list, unless the value of the + @scheme[use-user-specific-search-paths] parameter is @scheme[#f].} + + @item{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.} + + @item{If the directory specified by @scheme[(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.} + + @item{If the @envvar{PLTCOLLECTS} environment variable is defined, it + is combined with the default list using + @scheme[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.} + +}} + + +@defproc[(collection-path [collection string?] ...+) path?]{ + +Returns the path to a directory containing the libraries of the +collection indicated by @scheme[collection]s, where the second +@scheme[collection] (if any) names a sub-collection, and so on. If the +collection is not found, the @exnraise[exn:fail:filesystem].} + + +@defparam[current-library-collection-paths paths (listof (and/c path? complete-path?))]{ + +Parameter that determines a list of complete directory paths for +library collections used by @scheme[require]. See +@secref["mz:collects"] for more information.} + + +@defboolparam[use-user-specific-search-paths on?]{ + +Parameter that determines whether user-specific paths, which are in +the directory produced by @scheme[(find-system-path 'addon-dir)], are +included in search paths for collections and other files. For example, +@scheme[find-library-collection-paths] omits the user-specific +collection directory when this parameter's value is @scheme[#f].} diff --git a/collects/scribblings/reference/filesystem.scrbl b/collects/scribblings/reference/filesystem.scrbl index a3fa81252c..7553c03f79 100644 --- a/collects/scribblings/reference/filesystem.scrbl +++ b/collects/scribblings/reference/filesystem.scrbl @@ -110,7 +110,7 @@ by @scheme[kind], which must be one of the following: initially to @scheme[program].} @item{@scheme['collects-dir] --- a path to the main collection - of libraries (see @secref["mz:mzlib"]). If this path is relative, it's + of libraries (see @secref["mz:collects"]). If this path is relative, it's relative to the directory of @scheme[(find-system-path 'exec-file)]. This path is normally embedded in the @exec{mzscheme} executable, but it can be overridden by the @DFlag{collects} or @Flag{X} @@ -150,7 +150,7 @@ directory as the executable. The result is then the full path for the found @scheme[related-sub], instead of the path for the executable. This procedure is used by the @exec{mzscheme} executable to find the -standard library collection directory (see @secref["mz:mzlib"]). In +standard library collection directory (see @secref["mz:collects"]). In this case, @scheme[program] is the name used to start MzScheme and @scheme[related] is @scheme["collects"]. The @scheme[related-sub] argument is used because, under @|AllUnix|, @scheme[program-sub] may diff --git a/collects/scribblings/reference/reference.scrbl b/collects/scribblings/reference/reference.scrbl index fe80899f5f..5642a1bc13 100644 --- a/collects/scribblings/reference/reference.scrbl +++ b/collects/scribblings/reference/reference.scrbl @@ -26,6 +26,7 @@ language. @include-section["security.scrbl"] @include-section["os.scrbl"] @include-section["memory.scrbl"] +@include-section["running.scrbl"] @;------------------------------------------------------------------------ diff --git a/collects/scribblings/reference/running.scrbl b/collects/scribblings/reference/running.scrbl new file mode 100644 index 0000000000..2e1a2324ef --- /dev/null +++ b/collects/scribblings/reference/running.scrbl @@ -0,0 +1,8 @@ +#reader(lib "docreader.ss" "scribble") +@require["mz.ss"] + +@title[#:tag "mz:running" #:style 'toc]{Running PLT Scheme} + +@local-table-of-contents[] + +@include-section["collects.scrbl"] diff --git a/collects/scribblings/reference/syntax.scrbl b/collects/scribblings/reference/syntax.scrbl index 84395a0b2e..c509cd74fa 100644 --- a/collects/scribblings/reference/syntax.scrbl +++ b/collects/scribblings/reference/syntax.scrbl @@ -1100,7 +1100,8 @@ corresponds to the default @tech{module name resolver}. least two path elements. All path elements up to the last one form a @tech{collection} path, which is used to locate the relevant directory (not relative to the containing source), and the last path - element refers to a file.} + element refers to a file. See @secref["mz:collects"] for more + information.} @specsubform[#:literals (file) (file string)]{Similar to the plain @scheme[rel-string] case, but @scheme[string] is a path (possibly