diff --git a/pkgs/racket-pkgs/racket-doc/scribblings/guide/hash-languages.scrbl b/pkgs/racket-pkgs/racket-doc/scribblings/guide/hash-languages.scrbl index a1a910e3b6..626b6056a2 100644 --- a/pkgs/racket-pkgs/racket-doc/scribblings/guide/hash-languages.scrbl +++ b/pkgs/racket-pkgs/racket-doc/scribblings/guide/hash-languages.scrbl @@ -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] diff --git a/pkgs/racket-pkgs/racket-doc/scribblings/guide/module-basics.scrbl b/pkgs/racket-pkgs/racket-doc/scribblings/guide/module-basics.scrbl index d387dc84cb..ac78cbd4e3 100644 --- a/pkgs/racket-pkgs/racket-doc/scribblings/guide/module-basics.scrbl +++ b/pkgs/racket-pkgs/racket-doc/scribblings/guide/module-basics.scrbl @@ -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