suzanne.soy/racket
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update Guide to describe adding a collection via a package

Browse Source
This commit is contained in:
Matthew Flatt 2013-08-25 08:26:31 -06:00
parent 94d61b9e96
commit 83d3304cdc
2 changed files with 101 additions and 114 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
pkgs/racket-pkgs/racket-doc/scribblings/guide/hash-languages.scrbl
View File

@ -201,56 +201,14 @@ access languages like @filepath{literal.rkt} and
@filepath{dollar-racket.rkt}. If you want to use something like @filepath{dollar-racket.rkt}. If you want to use something like
@racket[@#,hash-lang[] literal] directly, then you must move @racket[@#,hash-lang[] literal] directly, then you must move
@filepath{literal.rkt} into a Racket @tech{collection} named @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 After moving the file and installing the package, you can use
also @secref["link-collection"]): @racket[literal] directly after @hash-lang[]:
@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[]:
@racketmod[ @racketmod[
@#,racket[literal] @#,racket[literal]

159
pkgs/racket-pkgs/racket-doc/scribblings/guide/module-basics.scrbl
View File

@ -119,17 +119,17 @@ program, compilation from source can take too long, so use
@commandline{raco make sort.rkt} @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 to compile @filepath{sort.rkt} and all its dependencies to bytecode
files. Running @exec{racket sort.rkt} will automatically use bytecode files. Running @exec{racket sort.rkt} will automatically use bytecode
files when they are present. 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} @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, module in a @tech{collection} is referenced through an unquoted,
suffixless path. For example, the following module refers to the suffixless path. For example, the following module refers to the
@filepath{date.rkt} library that is part of the @filepath{racket} @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} @item{Second, @racket[require] implicitly adds a @filepath{.rkt}
suffix to the path.} suffix to the path.}
@item{Finally, @racket[require] treats the path as relative to the @item{Finally, @racket[require] resolves the path by searching among
installation location of the collection, instead of relative to installed @tech{collections}, instead of treating the path as relative to
the enclosing module's path.} the enclosing module's path.}
] ]
The @filepath{racket} collection is located in a directory with the To a first approximation, a @tech{collection} is implemented as a
Racket installation. A user-specific directory can contain additional filesystem directory. For example, the @filepath{racket} collection is
collections, and even more collection directories can be specified in mostly located in a @filepath{racket} directory within the Racket
configuration files or through the @envvar{PLTCOLLECTS} search installation's @filepath{collects} directory, as reported by
path. Try running the following program to find out how your
collection search path is configured:
@racketmod[ @racketmod[
racket racket
(require setup/dirs) (require setup/dirs)
(find-collects-dir) (code:comment @#,t{main collection directory}) (build-path (find-collects-dir) (code:comment @#,t{main collection directory})
(find-user-collects-dir) (code:comment @#,t{user-specific collection directory}) "racket")
(get-collects-search-dirs) (code:comment @#,t{complete search path})
] ]
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} @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 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 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[ You could add a new collection by placing files in the Racket
installation or one of the directories reported by
@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
@racket[(get-collects-search-dirs)]. Alternatively, you could add to @racket[(get-collects-search-dirs)]. Alternatively, you could add to
the list of searched directories by setting the @envvar{PLTCOLLECTS} the list of searched directories by setting the @envvar{PLTCOLLECTS}
environment variable; if you set @envvar{PLTCOLLECTS}, include an environment variable.@margin-note*{If you set @envvar{PLTCOLLECTS},
empty path in by starting the value with a colon (Unix and Mac OS X) include an empty path in by starting the value with a colon (Unix and
or semicolon (Windows) so that the original search paths are Mac OS X) or semicolon (Windows) so that the original search paths are
preserved. Finally, instead of using one of the default directories or preserved.} The best option, however, is to add a @tech{package}.
setting @envvar{PLTCOLLECTS}, you can use @exec{raco link}.
The @exec{raco link} command-line tool creates a link from a Creating a package @emph{does not} mean that you have to register with
collection name to a directory for the collection's modules. For a package server or perform a bundling step that copies your source
example, suppose you have a directory @filepath{/usr/molly/bakery} 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 that contains the @filepath{cake.rkt} module (from the
@seclink["module-basics"]{beginning} of this section) and other @seclink["module-basics"]{beginning} of this section) and other
related modules. To make the modules available as a @filepath{bakery} related modules. To make the modules available as a @filepath{bakery}
collection, use @margin-note*{Instead of installing a single collection, either
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}.}
@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 Afterward, @racket[(require bakery/cake)] from any module will import
the @racket[print-cake] function from the @racket[print-cake] function from
@filepath{/usr/molly/bakery/cake.rkt}. @filepath{/usr/molly/bakery/cake.rkt}.
To make a collection name different from the name of the directory By default, the name of the directory that you install is used both as
that contains the collection's modules, use the @DFlag{name} or the @tech{package} name and as the @tech{collection} that is provided
@Flag{n} option for @exec{raco link}. By default, @exec{raco link} by the package. Also, the package manager normally defaults to
installs a collection link only for the current user, but you can installation only for the current user, as opposed to all users of a
supply the @DFlag{installation} or @Flag{i} flag to install the link Racket installation. See @other-manual['(lib
for all users of your Racket installation. "pkg/scribblings/pkg.scrbl")] for more information.
@margin-note{See @secref[#:doc '(lib "scribblings/raco/raco.scrbl") If you intend to distribute your libraries to others, choose
"link"] for more information on @exec{raco link}.} collection and package names carefully. The collection namespace is
hierarchical, but top-level collection names are global, and the
If you intend to distribute your library collection to others, choose package namespace is flat. Consider putting one-off libraries under
the collection name carefully. The collection namespace is some top-level name like @filepath{molly} that identifies the
hierarchical, but (unlike @|PLaneT|) the collection system has no producer. Use a collection name like @filepath{bakery} when producing
built-in feature to avoid conflicts from different producers or the definitive collection of baked-goods libraries.
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.
After your libraries are put in a @tech{collection} you can still 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 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} and more convenient to use @exec{raco setup}. The @exec{raco setup}
command takes a collection name (as opposed to a file name) and 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 build documentation for the collection and add it to the documentation
index, as specified by a @filepath{info.rkt} module in the collection. index, as specified by a @filepath{info.rkt} module in the collection.
See @secref[#:doc '(lib "scribblings/raco/raco.scrbl") "setup"] for See @secref[#:doc '(lib "scribblings/raco/raco.scrbl") "setup"] for