package-manager documentation edits
This commit is contained in:
Matthew Flatt
parent
7ea19bf951
commit
1cf06ae138
|
|
@ -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}}
|
||||
|
||||
|
|
|
|||
|
|
@ -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}.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user