update Guide to describe adding a collection via a package
This commit is contained in:
Matthew Flatt
parent
94d61b9e96
commit
83d3304cdc
|
|
@ -201,56 +201,14 @@ access languages like @filepath{literal.rkt} and
|
|||
@filepath{dollar-racket.rkt}. If you want to use something like
|
||||
@racket[@#,hash-lang[] literal] directly, then you must move
|
||||
@filepath{literal.rkt} into a Racket @tech{collection} named
|
||||
@filepath{literal}.
|
||||
@filepath{literal} (see also @secref["link-collection"]).
|
||||
Specifically, move @filepath{literal.rkt} to
|
||||
@filepath{literal/lang/reader.rkt} for any directory name
|
||||
@filepath{literal}. Then, install the @filepath{literal}
|
||||
directory as a package.
|
||||
|
||||
There are two ways to create the @filepath{literal} collection (see
|
||||
also @secref["link-collection"]):
|
||||
|
||||
@itemlist[
|
||||
|
||||
@item{You can create a directory either in the main Racket
|
||||
installation or in a user-specific directory. Use
|
||||
@racket[find-collects-dir] or @racket[find-user-collects-dir]
|
||||
from @racketmodname[setup/dirs] to find the directory:
|
||||
|
||||
@interaction[
|
||||
(require setup/dirs)
|
||||
(eval:alts (find-user-collects-dir)
|
||||
(build-path "/home/racketeer/.racket/"
|
||||
(version)
|
||||
"collects"))
|
||||
]
|
||||
|
||||
Move @filepath{literal.rkt} to
|
||||
@filepath{literal/lang/reader.rkt} within the directory reported
|
||||
by @racket[find-collects-dir] or
|
||||
@racket[find-user-collects-dir]. That is, the file
|
||||
@filepath{literal.rkt} must be renamed to @filepath{reader.rkt}
|
||||
and placed in a @filepath{lang} sub-directory of the
|
||||
@filepath{literal} collection.
|
||||
|
||||
@racketblock[
|
||||
.... @#,elem{(the main installation or the user's space)}
|
||||
!- @#,filepath{collects}
|
||||
!- @#,filepath{literal}
|
||||
!- @#,filepath{lang}
|
||||
!- @#,filepath{reader.rkt}
|
||||
]}
|
||||
|
||||
@item{Alternatively, move @filepath{literal.rkt} to
|
||||
@filepath{literal/lang/reader.rkt} for any directory name
|
||||
@filepath{literal}. Then, in the directory that contains
|
||||
@filepath{literal}, use the command line
|
||||
|
||||
@commandline{raco link literal}
|
||||
|
||||
to register the @filepath{literal} directory as the
|
||||
@filepath{literal} collection.}
|
||||
|
||||
]
|
||||
|
||||
After moving the file, you can use @racket[literal] directly after
|
||||
@hash-lang[]:
|
||||
After moving the file and installing the package, you can use
|
||||
@racket[literal] directly after @hash-lang[]:
|
||||
|
||||
@racketmod[
|
||||
@#,racket[literal]
|
||||
|
|
|
|||
|
|
@ -119,17 +119,17 @@ program, compilation from source can take too long, so use
|
|||
|
||||
@commandline{raco make sort.rkt}
|
||||
|
||||
@margin-note{See @secref[#:doc '(lib "scribblings/raco/raco.scrbl")
|
||||
"make"] for more information on @exec{raco make}.}
|
||||
|
||||
to compile @filepath{sort.rkt} and all its dependencies to bytecode
|
||||
files. Running @exec{racket sort.rkt} will automatically use bytecode
|
||||
files when they are present.
|
||||
|
||||
@margin-note{See @secref[#:doc '(lib "scribblings/raco/raco.scrbl")
|
||||
"make"] for more information on @exec{raco make}.}
|
||||
|
||||
@; ----------------------------------------
|
||||
@section{Library Collections}
|
||||
|
||||
A @deftech{collection} is a set of installed library modules. A
|
||||
A @deftech{collection} is a hierarchical grouping of installed library modules. A
|
||||
module in a @tech{collection} is referenced through an unquoted,
|
||||
suffixless path. For example, the following module refers to the
|
||||
@filepath{date.rkt} library that is part of the @filepath{racket}
|
||||
|
|
@ -167,29 +167,60 @@ collection-based module path:
|
|||
@item{Second, @racket[require] implicitly adds a @filepath{.rkt}
|
||||
suffix to the path.}
|
||||
|
||||
@item{Finally, @racket[require] treats the path as relative to the
|
||||
installation location of the collection, instead of relative to
|
||||
@item{Finally, @racket[require] resolves the path by searching among
|
||||
installed @tech{collections}, instead of treating the path as relative to
|
||||
the enclosing module's path.}
|
||||
|
||||
]
|
||||
|
||||
The @filepath{racket} collection is located in a directory with the
|
||||
Racket installation. A user-specific directory can contain additional
|
||||
collections, and even more collection directories can be specified in
|
||||
configuration files or through the @envvar{PLTCOLLECTS} search
|
||||
path. Try running the following program to find out how your
|
||||
collection search path is configured:
|
||||
To a first approximation, a @tech{collection} is implemented as a
|
||||
filesystem directory. For example, the @filepath{racket} collection is
|
||||
mostly located in a @filepath{racket} directory within the Racket
|
||||
installation's @filepath{collects} directory, as reported by
|
||||
|
||||
@racketmod[
|
||||
racket
|
||||
|
||||
(require setup/dirs)
|
||||
|
||||
(find-collects-dir) (code:comment @#,t{main collection directory})
|
||||
(find-user-collects-dir) (code:comment @#,t{user-specific collection directory})
|
||||
(get-collects-search-dirs) (code:comment @#,t{complete search path})
|
||||
(build-path (find-collects-dir) (code:comment @#,t{main collection directory})
|
||||
"racket")
|
||||
]
|
||||
|
||||
The Racket installation's @filepath{collects} directory, however, is
|
||||
only one place that @racket[require] looks for collection directories.
|
||||
Other places include the user-specific directory reported by
|
||||
@racket[(find-user-collects-dir)] and directories configured through
|
||||
the @envvar{PLTCOLLECTS} search path. Finally, and most typically,
|
||||
collections are found through installed @tech{packages}.
|
||||
|
||||
@; ----------------------------------------
|
||||
@section[#:tag "packages-and-collections"]{Packages and Collections}
|
||||
|
||||
A @deftech{package} is a set of libraries that are installed through
|
||||
the Racket package manager (or included as pre-installed in a Racket
|
||||
distribution). For example, the @racketmodname[racket/gui] library is
|
||||
provided by the @filepath{gui} package, while
|
||||
@racketmodname[parser-tools/lex] is provided by the
|
||||
@filepath{parser-tools} library.@margin-note{More precisely,
|
||||
@racketmodname[racket/gui] is provided by @filepath{gui-lib},
|
||||
@racketmodname[parser-tools/lex] is provided by
|
||||
@filepath{parser-tools}, and the @filepath{gui} and
|
||||
@filepath{parser-tools} packages extend @filepath{gui-lib} and
|
||||
@filepath{parser-tools-lib} with documentation.}
|
||||
|
||||
Racket programs do not refer to @tech{packages} directly. Instead,
|
||||
programs refer to libraries via @tech{collections}, and adding or
|
||||
removing a @tech{package} changes the set of collection-based
|
||||
libraries that are available. A single package can supply
|
||||
libraries in multiple collections, and two different packages can
|
||||
supply libraries in the same collection (but not the same libraries,
|
||||
and the package manager ensures that installed packages do not
|
||||
conflict at that level).
|
||||
|
||||
For more information about packages, see @other-manual['(lib
|
||||
"pkg/scribblings/pkg.scrbl")].
|
||||
|
||||
@; ----------------------------------------
|
||||
@section[#:tag "link-collection"]{Adding Collections}
|
||||
|
||||
|
|
@ -205,75 +236,73 @@ your Racket configuration.
|
|||
|
||||
Some libraries are meant to be used across multiple projects, so that
|
||||
keeping the library source in a directory with its uses does not make
|
||||
sense. In that case, you have two options:
|
||||
sense. In that case, the best option is add a new
|
||||
@tech{collection}. After the library is in a collection, it can be
|
||||
referenced with an unquoted path, just like libraries that are
|
||||
included with the Racket distribution.
|
||||
|
||||
@itemlist[
|
||||
|
||||
@item{Add the library to a new or existing @tech{collection}. After
|
||||
the library is in a collection, it can be referenced with an
|
||||
unquoted path, just like libraries that are included with the
|
||||
Racket distribution.}
|
||||
|
||||
@item{Add the library to a new or existing @|PLaneT| package. Libraries
|
||||
in a @|PLaneT| package are referenced with a path of the form
|
||||
@racket[(planet ....)] path.
|
||||
@margin-note*{See @other-doc['(lib "planet/planet.scrbl")]
|
||||
for more information on @|PLaneT|.}}
|
||||
|
||||
]
|
||||
|
||||
The simplest option is to add a new collection. You could add a new
|
||||
collection by placing files in the Racket installation or one of the
|
||||
directories reported by
|
||||
You could add a new collection by placing files in the Racket
|
||||
installation or one of the directories reported by
|
||||
@racket[(get-collects-search-dirs)]. Alternatively, you could add to
|
||||
the list of searched directories by setting the @envvar{PLTCOLLECTS}
|
||||
environment variable; if you set @envvar{PLTCOLLECTS}, include an
|
||||
empty path in by starting the value with a colon (Unix and Mac OS X)
|
||||
or semicolon (Windows) so that the original search paths are
|
||||
preserved. Finally, instead of using one of the default directories or
|
||||
setting @envvar{PLTCOLLECTS}, you can use @exec{raco link}.
|
||||
environment variable.@margin-note*{If you set @envvar{PLTCOLLECTS},
|
||||
include an empty path in by starting the value with a colon (Unix and
|
||||
Mac OS X) or semicolon (Windows) so that the original search paths are
|
||||
preserved.} The best option, however, is to add a @tech{package}.
|
||||
|
||||
The @exec{raco link} command-line tool creates a link from a
|
||||
collection name to a directory for the collection's modules. For
|
||||
example, suppose you have a directory @filepath{/usr/molly/bakery}
|
||||
Creating a package @emph{does not} mean that you have to register with
|
||||
a package server or perform a bundling step that copies your source
|
||||
code into an archive format. Creating a package can simply mean using
|
||||
the package manager to make your libraries locally accessible as a
|
||||
collection from their current source locations.
|
||||
|
||||
For example, suppose you have a directory @filepath{/usr/molly/bakery}
|
||||
that contains the @filepath{cake.rkt} module (from the
|
||||
@seclink["module-basics"]{beginning} of this section) and other
|
||||
related modules. To make the modules available as a @filepath{bakery}
|
||||
collection, use @margin-note*{Instead of installing a single
|
||||
collection directory, the @DFlag{root} or @Flag{d} flag for @exec{raco
|
||||
link} can install a directory that contains collections, much like
|
||||
adding to @envvar{PLTCOLLECTS}.}
|
||||
collection, either
|
||||
|
||||
@commandline{raco link /usr/molly/bakery}
|
||||
@itemlist[
|
||||
|
||||
@item{Use the @exec{raco pkg} command-line tool:
|
||||
|
||||
@commandline{raco pkg install --link /usr/molly/bakery}
|
||||
|
||||
where the @DFlag{link} flag is not actually needed when the
|
||||
provided path includes a directory separator.}
|
||||
|
||||
@item{Use DrRacket's @onscreen{Package Manager} item from the
|
||||
@onscreen{File} menu. In the @onscreen{Do What I Mean} panel,
|
||||
click @onscreen{Browse...}, choose the
|
||||
@filepath{/usr/molly/bakery} directory, and click
|
||||
@onscreen{Install}.}
|
||||
|
||||
]
|
||||
|
||||
Afterward, @racket[(require bakery/cake)] from any module will import
|
||||
the @racket[print-cake] function from
|
||||
@filepath{/usr/molly/bakery/cake.rkt}.
|
||||
|
||||
To make a collection name different from the name of the directory
|
||||
that contains the collection's modules, use the @DFlag{name} or
|
||||
@Flag{n} option for @exec{raco link}. By default, @exec{raco link}
|
||||
installs a collection link only for the current user, but you can
|
||||
supply the @DFlag{installation} or @Flag{i} flag to install the link
|
||||
for all users of your Racket installation.
|
||||
By default, the name of the directory that you install is used both as
|
||||
the @tech{package} name and as the @tech{collection} that is provided
|
||||
by the package. Also, the package manager normally defaults to
|
||||
installation only for the current user, as opposed to all users of a
|
||||
Racket installation. See @other-manual['(lib
|
||||
"pkg/scribblings/pkg.scrbl")] for more information.
|
||||
|
||||
@margin-note{See @secref[#:doc '(lib "scribblings/raco/raco.scrbl")
|
||||
"link"] for more information on @exec{raco link}.}
|
||||
|
||||
If you intend to distribute your library collection to others, choose
|
||||
the collection name carefully. The collection namespace is
|
||||
hierarchical, but (unlike @|PLaneT|) the collection system has no
|
||||
built-in feature to avoid conflicts from different producers or
|
||||
different versions. Consider putting one-off libraries under some
|
||||
top-level name like @filepath{molly} that identifies the producer.
|
||||
Use a collection name like @filepath{bakery} when producing the
|
||||
definitive collection of baked-goods libraries.
|
||||
If you intend to distribute your libraries to others, choose
|
||||
collection and package names carefully. The collection namespace is
|
||||
hierarchical, but top-level collection names are global, and the
|
||||
package namespace is flat. Consider putting one-off libraries under
|
||||
some top-level name like @filepath{molly} that identifies the
|
||||
producer. Use a collection name like @filepath{bakery} when producing
|
||||
the definitive collection of baked-goods libraries.
|
||||
|
||||
After your libraries are put in a @tech{collection} you can still
|
||||
use @exec{raco make} to compile the library sources, but it's better
|
||||
and more convenient to use @exec{raco setup}. The @exec{raco setup}
|
||||
command takes a collection name (as opposed to a file name) and
|
||||
compiles all libraries within the collection. In addition, it can
|
||||
compiles all libraries within the collection. In addition, @exec{raco setup} can
|
||||
build documentation for the collection and add it to the documentation
|
||||
index, as specified by a @filepath{info.rkt} module in the collection.
|
||||
See @secref[#:doc '(lib "scribblings/raco/raco.scrbl") "setup"] for
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user