From 1cf06ae1383aa4f6a6952500314b2a48a5d649c8 Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Wed, 21 Aug 2013 14:07:07 -0600 Subject: [PATCH] package-manager documentation edits --- .../pkg/scribblings/getting-started.scrbl | 60 ++++++++---- .../racket-doc/pkg/scribblings/pkg.scrbl | 93 +++++++++++++------ 2 files changed, 107 insertions(+), 46 deletions(-) diff --git a/pkgs/racket-pkgs/racket-doc/pkg/scribblings/getting-started.scrbl b/pkgs/racket-pkgs/racket-doc/pkg/scribblings/getting-started.scrbl index 1d9557b25e..ba30c80d42 100644 --- a/pkgs/racket-pkgs/racket-doc/pkg/scribblings/getting-started.scrbl +++ b/pkgs/racket-pkgs/racket-doc/pkg/scribblings/getting-started.scrbl @@ -38,7 +38,7 @@ operations. A @tech{package} is not something that you refer to directly in your Racket programs. Instead, a @tech{package} is a set of libraries that -fit into the @rtech{collection} hierarchy, and you refer to liraries +fit into the @rtech{collection} hierarchy, and you refer to libraries through their @rtech{collection}-based paths. Libraries that are close in the hierarchy may be provided by different packages, while a single package may provide libraries that are far from each other in the @@ -83,7 +83,7 @@ package: [none] } -The ``Checksum'' column reports the specific ``version'' of each +The ``Checksum'' column reports the specific implementation of each package that is installed. A package can have a @tech{version} in a more traditional sense, but the @tech{checksum} is the ``version'' as far as the package system is concerned. When you request an update, @@ -101,7 +101,7 @@ installation. We discuss other possibilities for ``Source'' in @secref["installing-packages"]. Neither the @pkgname{main-distribution} package nor the -@pkgname{racket-lib} package actually provide any libraries on its own, +@pkgname{racket-lib} package actually provides any libraries on its own, but each declares dependencies on other packages. The @pkgname{racket-lib} package depends on native-library packages, if any, for your platform. The @pkgname{main-distribution} package @@ -115,14 +115,14 @@ packages you have explicitly selected for your installation). @commandline{raco pkg show --all} An asterisk appears beside the name of every package that was -``auto-installed'' to satisfy a dependency. All ``auto-installed'' +``auto-installed'' to satisfy a dependency. All auto-installed packages are as available for your use in the same way as explicitly installed packages, but normally your code should refer only to packages that you have explicitly installed. The difference between an -``auto-installed'' and an explicitly installed package is how various +auto-installed and an explicitly installed package is how various commands, such as @command-ref{show}, treat the package. If you specifically request installation of a package that is -``auto-installed'', then the package is promoted and thereafter +auto-installed, then the package is promoted and thereafter treated as a explicitly installed package. @; ---------------------------------------- @@ -166,11 +166,10 @@ use the package's name with @command-ref{install}: If the package depends on other packages that you do not have installed already, then @command-ref{install} will alert you and ask -whether it should install them, too. Use @exec{@DFlag{deps} search-auto} to +whether it should install them, too. Use @DFlag{auto} to skip the question and make dependencies installed automatically. Either way, packages installed to satisfy dependencies are marked as -``auto-installed,'' which makes them easier to uninstall when the -dependent packages are installed, and it also makes them hidden by +auto-installed, which makes them easier to uninstall, and it also makes them hidden by default for @command-ref{show} (since packages that are installed for dependencies are an implementation detail that you usually do not care about). @@ -182,8 +181,8 @@ catalog}. In general, each argument to @command-ref{install} is a @filepath{.zip} file, a @filepath{.tar} file, a Github repository, a directory-structured web site, or a few other possibilities. In each of those cases, a @tech{package name} is inferred from the -@tech{package source}; after the package is installed, you use the -name with other @exec{raco pkg} commands to refer to the installed +@tech{package source}. After the package is installed, you use the +package name with other @exec{raco pkg} commands to refer to the installed package. In fact, a @tech{package catalog} does not actually serve package @@ -201,9 +200,13 @@ update. @section[#:tag "updating-packages"]{Updating Packages} If your package installations become out of date, you can update -packages with @command-ref{update}. Either specify individual -packages to update, or use @DFlag{all} to update all installed -packages for which a new @tech{checksum} is available. +packages with @command-ref{update}: + +@commandline{raco pkg update @nonterm{pkg-name}} + +Either specify individual packages to update, or use @DFlag{all} to +update all installed packages for which a new @tech{checksum} is +available. The way that the package manager finds updates depends on the way that a package was installed. If it was installed by using a @tech{package @@ -236,6 +239,27 @@ a new @tech{checksum} at a previously specified source. @; ---------------------------------------- +@section[#:tag "removing-packages"]{Removing Packages} + +As you might expect, @command-ref{remove} removes a package: + +@commandline{raco pkg remove @nonterm{pkg-name}} + +If the installation of a package triggered auto-installs of other +packages, then removing the package @emph{does not} automatically +remove the auto-installed packages. Supply the @DFlag{auto} flag for +@command-ref{remove}, either by itself or when uninstalling packages, +to also remove any auto-installed packages that are left without +dependents. + +The @command-ref{remove} command will not remove a package if other +installed packages depend on it, unless you force the removal. If you want +to demote a package from explicitly installed to auto-installed (for +clean-up later, perhaps when other packages are removed), then +supply the @DFlag{demote} flag to @command-ref{remove}. + +@; ---------------------------------------- + @section[#:tag "how-to-create"]{Creating Packages} A package normally starts life as a directory containing module files @@ -283,7 +307,7 @@ development directory as a locally installed package. Use If you use @command-ref{show} at this point, you'll see a line for @nonterm{pkg-name}. The ``Source'' column will show that it's a -linked package, and the ``Checksum'' column will say @litchar{#f}, +linked package, and the ``Checksum'' column will say @tt{#f}, which means that there is no checksum. Sub-commands like @command-ref{update} will not work on a linked package, because ``updates'' to the package happen whenever you modify the package's @@ -314,11 +338,11 @@ dependencies and help you figure out what dependencies to declare.) Even for a @tech{single-collection package}, you may want to create @filepath{info.rkt} and include the definition -@racketblock[(define collection @{"}@nonterm{pkg-name}@{"})] +@racketblock[(define collection @#,racketvalfont{"}@#,nonterm{pkg-name}@#,racketvalfont{"})] This definition may seem redundant, since @nonterm{pkg-name} is available as the name of the enclosing directory, but declaring the -collection name explicitly prevents the meaning of your implementation +collection name explicitly prevents the meaning of your package's implementation from depending on the way that the implementation is referenced. Finally, in the case of a @tech{multi-collection package}, note that @@ -379,7 +403,7 @@ Then, upload the archive and its @tech{checksum} to your site: @commandline{scp @nonterm{package}.zip @nonterm{package}.zip.CHECKSUM your-host:public_html/} -Your @tech{package source} is then +Your @tech{package source} is then something like @inset{@exec{http://your-host/~@nonterm{user}/@nonterm{package}.zip}} diff --git a/pkgs/racket-pkgs/racket-doc/pkg/scribblings/pkg.scrbl b/pkgs/racket-pkgs/racket-doc/pkg/scribblings/pkg.scrbl index 34bb5592d4..6618cb3932 100644 --- a/pkgs/racket-pkgs/racket-doc/pkg/scribblings/pkg.scrbl +++ b/pkgs/racket-pkgs/racket-doc/pkg/scribblings/pkg.scrbl @@ -63,7 +63,7 @@ Each @tech{package} has associated @deftech{package metadata}: package can be updated when its @tech{checksum} changes, whether or not its @tech{version} changes. The checksum can be computed as the SHA1 (see @racketmodname[openssl/sha1]) - of the package's source.} + of the package's content.} @item{a @deftech{version} --- a string of the form @nonterm{maj}@litchar{.}@nonterm{min}, @nonterm{maj}@litchar{.}@nonterm{min}@litchar{.}@nonterm{sub}, or @nonterm{maj}@litchar{.}@nonterm{min}@litchar{.}@nonterm{sub}@litchar{.}@nonterm{rel}, @@ -82,6 +82,8 @@ name as the package. The @tech{checksum} is typically left implicit. The package directory can contain a file named @filepath{info.rkt} to declare other metadata (see @secref["metadata"]). +@subsection[#:tag "concept:multi-collection"]{Single-collection and Multi-collection Packages} + A @tech{package} can be a @tech{single-collection package} or a @tech{multi-collection package}: @@ -103,26 +105,33 @@ A @tech{package} can be a @tech{single-collection package} or a ] -More generally, a @deftech{package source} identifies a @tech{package} +@subsection[#:tag "concept:source"]{Package Sources} + +A @deftech{package source} identifies a @tech{package} representation. Each package source type has a different way of storing the @tech{checksum} and providing the package content (usually with @tech{single-collection package} and @tech{multi-collection -package} variants). The valid @tech{package source} types are: +package} variants). + +The @tech{package source} types are: @itemlist[ @item{a local file path naming an archive -- The name of the package is the basename of the archive file. The @tech{checksum} for archive -@filepath{f.@nonterm{ext}} is given by the file @filepath{f.@nonterm{ext}.CHECKSUM}. For -example, @filepath{~/tic-tac-toe.zip}'s @tech{checksum} would be inside -@filepath{~/tic-tac-toe.zip.CHECKSUM}. The valid archive formats +@filepath{f.@nonterm{ext}} is given by the file @filepath{f.@nonterm{ext}.CHECKSUM}. +The valid archive formats are (currently) @filepath{.zip}, @filepath{.tar}, @filepath{.tgz}, @filepath{.tar.gz}, and @filepath{.plt}, each of which represents package content analogous -to a directory , +to a directory, but the @filepath{.plt} format does not accommodate a @tech{single-collection package} representation. +For +example, @filepath{~/tic-tac-toe.zip}'s @tech{checksum} would be inside +@filepath{~/tic-tac-toe.zip.CHECKSUM}. + A package source is inferred to refer to a file only when it has a suffix matching a valid archive format and when it starts with @litchar{file://} or does not start @@ -130,7 +139,9 @@ with alphabetic characters followed by @litchar{://}. The inferred package name is the filename without its suffix.} @item{a local directory -- The name of the package is the name of the -directory. The @tech{checksum} is not present. For example, +directory. The @tech{checksum} is not present. + +For example, @filepath{~/tic-tac-toe/} is directory package source. A package source is inferred to refer @@ -142,7 +153,9 @@ package name is the directory name.} @item{a remote URL naming an archive -- This type follows the same rules as a local file path, but the archive and @tech{checksum} files are -accessed via HTTP(S). For example, +accessed via HTTP(S). + +For example, @filepath{http://game.com/tic-tac-toe.zip} is a remote URL package source whose @tech{checksum} is found at @filepath{http://game.com/tic-tac-toe.zip.CHECKSUM}. @@ -159,7 +172,9 @@ contain a file named @filepath{MANIFEST} that lists all the contingent files. These are downloaded into a local directory and then the rules for local directory paths are followed. However, if the remote directory contains a file named @filepath{.CHECKSUM}, then it is used -to determine the @tech{checksum}. For example, +to determine the @tech{checksum}. + +For example, @filepath{http://game.com/tic-tac-toe/} is a directory URL package source whose @tech{checksum} is found at @filepath{http://game.com/tic-tac-toe/.CHECKSUM}. @@ -172,8 +187,11 @@ is the directory name.} @item{a remote URL naming a GitHub repository -- The format for such URLs is: -@inset{@exec{github://github.com/}@nonterm{user}@exec{/}@nonterm{repository}@; -@exec{/}@nonterm{branch-or-tag}@exec{/}@nonterm{optional-subpath}} +@inset{@exec{github://github.com/}@nonterm{user}@exec{/}@nonterm{repo}@; +@exec{/}@nonterm{branch-or-tag}@exec{/}@nonterm{subpath}} + +where @nonterm{subpath} is optional and can contain multiple +@litchar{/}-separated elements. For example, @filepath{github://github.com/game/tic-tac-toe/master/} is a GitHub package source. @@ -187,11 +205,13 @@ A package source is inferred to be a GitHub reference when it starts with @litchar{github://}; a package source that is otherwise specified as a GitHub reference is automatically prefixed with @filepath{github://github.com/}. The inferred package name -is the last element of @nonterm{optional-subpath} if it is -non-empty, otherwise the inferred name is @nonterm{repository}.} +is the last element of @nonterm{subpath} if it is +non-empty, otherwise the inferred name is @nonterm{repo}.} @item{a @tech{package name} -- A @tech{package catalog} is -consulted to determine the source and @tech{checksum} for the package. For +consulted to determine the source and @tech{checksum} for the package. + +For example, @exec{tic-tac-toe} is a package name that can be used as a package source. @@ -201,6 +221,8 @@ means that it has only the characters @|package-name-chars|.} ] +@subsection[#:tag "concept:catalog"]{Package Catalogs} + A @deftech{package catalog} is a server or database that converts package names to other package sources. A @tech{package catalog} is identified by a string representing a URL, where a @litchar{http://} or @litchar{https://} @@ -215,33 +237,46 @@ generated packages for old @|PLaneT| packages. Anyone may host a as a basic @tech{package catalog} server. See @secref["catalog-protocol"] for information on how package information is extracted from a catalog. -After a package is installed, the original source of its installation +@subsection[#:tag "concept:auto"]{Explicit vs@|._| Auto-Installation} + +When a package is installed, the original source of its installation is recorded, as well as whether the instalation was an @tech{automatic installation}. An @deftech{automatic installation} is one that was installed because it was a dependency of a non-@tech{automatic installation} package. +@subsection[#:tag "concept:conflicts"]{Package Conflicts} + Two packages are in @deftech{conflict} if they contain the same module. For example, if the package @pkgname{tic-tac-toe} contains the module file @filepath{data/matrix.rkt} and the package @pkgname{factory-optimize} contains the module file @filepath{data/matrix.rkt}, then @pkgname{tic-tac-toe} and -@pkgname{factory-optimize} are in conflict. A package may also be in +@pkgname{factory-optimize} are in conflict. + +A package may also be in conflict with Racket itself, if it contains a module file that is part -of the core Racket distribution. For example, any package that -contains @filepath{racket/list.rkt} is in conflict with Racket. For -the purposes of conflicts, a module is a file that ends in -@filepath{.rkt} or @filepath{.ss}. +of the base Racket implementation. For example, any package that +contains @filepath{racket/list.rkt} is in conflict with Racket. + +For the purposes of conflicts, a module is a file that ends in +@filepath{.rkt}, @filepath{.ss}, or @filepath{.scrbl}. + +@subsection[#:tag "concept:updates"]{Package Updates} Package A is a @deftech{package update} of Package B if (1) B is installed, (2) A and B have the same name, and (3) A's @tech{checksum} is -different than B's. Note that a package @tech{version} is not taken +different than B's. A @tech{single-collection package} +can be a @tech{package update} of a @tech{multi-collection package} +and vice versa. + +Note that a package @tech{version} is not taken into account when determining a @tech{package update}, although a change in a package's @tech{version} (in either direction) implies a change in the @tech{checksum} because the checksum is computed from the package source and the meta-data that specifies -the version is part of the source. A @tech{single-collection package} -can be a @tech{package update} of a @tech{multi-collection package} -and vice versa. +the version is part of the source. + +@subsection[#:tag "concept:scope"]{Package Scopes} A @deftech{package scope} determines the effect of package installations, updates, @|etc|, with respect to different users and @@ -251,15 +286,17 @@ specific to both the current user and the installation's name/version (in the sense of @racket[get-installation-name]). The @exec{installation} scope means that package operations affect all users of the Racket installation. -Finally, a directory path can be used as a @tech{package scope}, in which case + +A directory path can be used as a @tech{package scope}, in which case package operations affect the set of packages installations in the -directory; an installation can be configured to include the +directory. An installation can be configured to include the directory in its search path for installed packages (see @secref["config-file" #:doc '(lib "scribblings/raco/raco.scrbl")]). + Conflict checking disallows installation of the same or conflicting package in different scopes, but if such a configuration is forced, collections are found first in packages with @exec{user} @tech{package -scope}; search then proceeds in a configured order, where +scope}. Search then proceeds in a configured order, where @exec{installation} @tech{package scope} typically precedes other directory @tech{package scopes}.