d8f9820ef3
A package catalog now supplies information about a package's modules and dependencies, so propagate it when copying a catalog, make the information accessible via `raco pkg catalog-show', and so on.
326 lines
12 KiB
Racket
326 lines
12 KiB
Racket
#lang scribble/manual
|
|
@(require (for-label (except-in racket/base
|
|
remove)
|
|
racket/contract/base
|
|
pkg
|
|
pkg/lib
|
|
(only-in pkg/db current-pkg-catalog-file)
|
|
net/url
|
|
syntax/modcollapse
|
|
setup/getinfo))
|
|
|
|
@title[#:tag "lib"]{Package Management Functions}
|
|
|
|
@defmodule[pkg/lib]{The @racketmodname[pkg/lib] library provides
|
|
building blocks on which the @racket[pkg] library and @exec{raco pkg}
|
|
commands are built.}
|
|
|
|
|
|
@deftogether[(
|
|
@defform[(with-pkg-lock body ...+)]
|
|
@defform[(with-pkg-lock/read-only body ...+)]
|
|
)]{
|
|
|
|
Evaluates the @racket[body]s while holding a lock to prevent
|
|
concurrent modification to the package database for the current
|
|
@tech{package scope}. Use the @racket[with-pkg-lock/read-only] form
|
|
for read-only access. The lock is reentrant but not upgradable from
|
|
read-only.
|
|
|
|
Use these form to wrap uses of functions from @racketmodname[pkg/lib]
|
|
that are documented to require the lock. Other functions from
|
|
@racketmodname[pkg/lib] take the lock as needed.}
|
|
|
|
@deftogether[(
|
|
@defparam[current-pkg-scope scope (or/c 'installation 'user 'shared)]
|
|
@defparam[current-pkg-scope-version s string?]
|
|
)]{
|
|
|
|
Parameters that together determine @tech{package scope} for management
|
|
operations and the version for version-specific scope.}
|
|
|
|
|
|
@defparam[current-pkg-error err procedure?]{
|
|
|
|
A parameter whose value is used to report errors that are normally
|
|
intended for an end uses. The arguments to the procedure are the same
|
|
as for @racket[error], except that an initial symbol argument is
|
|
omitted.
|
|
|
|
The default value uses @racket[error] with @racket['pkg] as the first
|
|
argument. The @exec{raco pkg} command sets this parameter to use
|
|
@racket[raise-user-error] with the sub-command name as its first
|
|
argument.}
|
|
|
|
|
|
@defparam[current-pkg-catalogs catalogs (or/c #f (listof url?))]{
|
|
|
|
A parameter that determines the @tech{package catalogs} that are
|
|
consulted to resolve a @tech{package name}. If the parameter's value
|
|
is @racket[#f], then the result of @racket[pkg-config-catalogs] is
|
|
used.}
|
|
|
|
|
|
@defproc[(pkg-config-catalogs) (listof string?)]{
|
|
|
|
Returns a list of URL strings for the user's configured @tech{package
|
|
catalogs}.}
|
|
|
|
|
|
@defstruct[pkg-info ([orig-pkg (or/c (list/c 'catalog string?)
|
|
(list/c 'url string?)
|
|
(list/c 'link string?))]
|
|
[checksum (or/c #f string?)]
|
|
[auto? boolean?])
|
|
#:prefab]{
|
|
|
|
A structure type that is used to report installed-package information.}
|
|
|
|
|
|
@defproc[(pkg-directory [name string?]) path-string?]{
|
|
|
|
Returns the directory that holds the installation of the installed
|
|
(in any scope) package @racket[name].}
|
|
|
|
|
|
@defproc[(path->pkg [path path-string?]) (or/c string? #f)]{
|
|
|
|
Returns the installed package containing @racket[path], if any.}
|
|
|
|
|
|
@defproc[(default-pkg-scope) (or/c 'installation 'user 'shared)]{
|
|
|
|
Returns the user's configured default @tech{package scope}.}
|
|
|
|
|
|
@defproc[(installed-pkg-names [#:scope scope (or/c #f 'installation 'user 'shared)])
|
|
(listof string?)]{
|
|
|
|
Returns a list of installed package names for the given @tech{package
|
|
scope}, where @racket[#f] indicates the user's default @tech{package
|
|
scope}.}
|
|
|
|
|
|
@defproc[(installed-pkg-table [#:scope scope (or/c #f 'installation 'user 'shared)])
|
|
(hash/c string? pkg-info?)]{
|
|
|
|
Returns a hash table of installed packages for the given @tech{package
|
|
scope}, where @racket[#f] indicates the user's default @tech{package
|
|
scope}.}
|
|
|
|
|
|
@deftogether[(
|
|
@defproc[(pkg-desc? [v any/c]) boolean?]
|
|
@defproc[(pkg-desc [name string?]
|
|
[type (or/c #f 'file 'dir 'link 'file-url 'dir-url 'github 'name)]
|
|
[checksum (or/c string? #f)]
|
|
[auto? boolean?])
|
|
pkg-desc?]
|
|
)]{
|
|
|
|
A @racket[pkg-desc] value describes a package source plus details of its
|
|
intended interpretation, where the @racket[auto?] field indicates that
|
|
the package is should be treated as installed automatically for a
|
|
dependency.}
|
|
|
|
|
|
@defproc[(pkg-stage [desc pkg-desc?]
|
|
[#:checksum checksum (or/c #f string?) #f])
|
|
(values path? (or/c #f string?) boolean?)]{
|
|
|
|
Locates the implementation of the package specified by @racket[desc] and
|
|
downloads and unpacks it to a temporary directory (as needed).
|
|
|
|
The result is the directory containing the unpacked package content,
|
|
the checksum (if any) for the unpacked package, and whether the
|
|
directory should be removed after the package content is no longer
|
|
needed.}
|
|
|
|
|
|
@defproc[(pkg-config [set? boolean?] [keys/vals list?])
|
|
void?]{
|
|
|
|
Implements the @racket[config] command.
|
|
|
|
The package lock must be held (allowing writes if @racket[set?] is true); see
|
|
@racket[with-pkg-lock].}
|
|
|
|
|
|
@defproc[(pkg-create [format (or/c 'zip 'tgz 'plt 'MANIFEST)]
|
|
[dir path-string?]
|
|
[#:quiet? quiet? boolean? #f])
|
|
void?]{
|
|
|
|
Implements the @racket[create] command.
|
|
|
|
Unless @racket[quiet?] is true, information about the output is repotred to the current output port.}
|
|
|
|
|
|
@defproc[(pkg-install [names (listof string?)]
|
|
[#:dep-behavior dep-behavior
|
|
(or/c #f 'fail 'force 'search-ask 'search-auto)
|
|
#f]
|
|
[#:force? force? boolean? #f]
|
|
[#:ignore-checksums? ignore-checksums? boolean? #f]
|
|
[#:quiet? boolean? quiet? #f])
|
|
(or/c #f (listof (or/c path-string?
|
|
(non-empty-listof path-string?))))]{
|
|
|
|
Implements the @racket[install] command. The result indicates which
|
|
collections should be setup via @exec{raco setup}: @racket[#f] means
|
|
all, and a list means only the indicated collections.
|
|
|
|
Status information and debugging details are mostly reported to a logger
|
|
named @racket['pkg], but information that is especially relevant to a
|
|
user (such as a download action) is reported to the current output
|
|
port, unless @racket[quiet?] is true.
|
|
|
|
The package lock must be held; see @racket[with-pkg-lock].}
|
|
|
|
|
|
@defproc[(pkg-update [names (listof string?)]
|
|
[#:dep-behavior dep-behavior
|
|
(or/c #f 'fail 'force 'search-ask 'search-auto)
|
|
#f]
|
|
[#:all? all? boolean? #f]
|
|
[#:deps? deps? boolean? #f]
|
|
[#:quiet? boolean? quiet? #f])
|
|
(or/c #f (listof (or/c path-string?
|
|
(non-empty-listof path-string?))))]{
|
|
|
|
Implements the @racket[update] command. The result is the same as for
|
|
@racket[install-pkgs].
|
|
|
|
The package lock must be held; see @racket[with-pkg-lock].}
|
|
|
|
|
|
@defproc[(pkg-remove [names (listof string?)]
|
|
[#:auto? auto? boolean? #f]
|
|
[#:force? force? boolean? #f]
|
|
[#:quiet? boolean? quiet? #f])
|
|
(or/c #f (listof (or/c path-string?
|
|
(non-empty-listof path-string?))))]{
|
|
|
|
Implements the @racket[remove] command. The result is the same as for
|
|
@racket[install-pkgs], indicating collects that should be setup
|
|
via @exec{raco setup}.
|
|
|
|
The package lock must be held; see @racket[with-pkg-lock].}
|
|
|
|
|
|
@defproc[(pkg-show [indent string?]
|
|
[#:directory show-dir? boolean? #f])
|
|
void?]{
|
|
|
|
Implements the @racket[show] command for a single package scope,
|
|
printing to the current output port. See also
|
|
@racket[installed-pkg-names] and @racket[installed-pkg-table].
|
|
|
|
The package lock must be held to allow reads; see
|
|
@racket[with-pkg-lock/read-only].}
|
|
|
|
|
|
@defproc[(pkg-catalog-show [names (listof string?)]
|
|
[#:all? all? boolean? #f]
|
|
[#:only-names? only-names? boolean? #f]
|
|
[#:modules? modules? boolean? #f])
|
|
void?]{
|
|
|
|
Implements the @racket[catalog-show] command. If @racket[all?] is true,
|
|
then @racket[names] should be empty.}
|
|
|
|
|
|
@defproc[(pkg-catalog-copy [sources (listof path-string?)]
|
|
[dest path-string?]
|
|
[#:from-config? from-config? boolean? #f]
|
|
[#:merge? merge? boolean? #f]
|
|
[#:force? force? boolean? #f]
|
|
[#:override? override? boolean? #f])
|
|
void?]{
|
|
|
|
Implements the @racket[catalog-copy] command.}
|
|
|
|
|
|
@defproc[(pkg-catalog-update-local [#:catalog-file catalog-file path-string? (current-pkg-catalog-file)]
|
|
[#:quiet? quiet? boolean? #f]
|
|
[#:consult-packages? consult-packages? boolean? #f])
|
|
void?]{
|
|
|
|
Consults the user's configured @tech{package catalogs} (like
|
|
@racket[pkg-catalog-copy]) and package servers (if
|
|
@racket[consult-packages?] is true) to populate the database
|
|
@racket[catalog-file] with information about available packages and the
|
|
modules that they implement.}
|
|
|
|
|
|
@defproc[(pkg-catalog-suggestions-for-module
|
|
[module-path module-path?]
|
|
[#:catalog-file catalog-file path-string? ....])
|
|
(listof string?)]{
|
|
|
|
Consults @racket[catalog-file] and returns a list of available packages
|
|
that provide the module specified by @racket[module-path].
|
|
|
|
The default @racket[catalog-file] is @racket[(current-pkg-catalog-file)]
|
|
if that file exists, otherwise a file in the racket installation is
|
|
tried.}
|
|
|
|
|
|
@defproc[(get-all-pkg-names-from-catalogs) (listof string?)]{
|
|
|
|
Consults @tech{package catalogs} to obtain a list of available
|
|
@tech{package names}.}
|
|
|
|
|
|
@defproc[(get-all-pkg-details-from-catalogs)
|
|
(hash/c string? (hash/c symbol? any/c))]{
|
|
|
|
Consults @tech{package catalogs} to obtain a hash table of available
|
|
@tech{package names} mapped to details about the package. Details for
|
|
a particular package are provided by a hash table that maps symbols
|
|
such as @racket['source], @racket['checksum], and @racket['author].}
|
|
|
|
|
|
@defproc[(get-pkg-details-from-catalogs [name string?])
|
|
(or/c #f (hash/c symbol? any/c))]{
|
|
|
|
Consults @tech{package catalogs} to obtain information for a
|
|
single @tech{package name}, returning @racket[#f] if the @tech{package
|
|
name} has no resolution. Details for the package are provided in the
|
|
same form as from @racket[get-all-pkg-details-from-catalogs].}
|
|
|
|
|
|
@defproc[(get-pkg-content [desc pkg-desc?]
|
|
[#:extract-info
|
|
extract-proc
|
|
((or/c #f
|
|
((symbol?) ((-> any)) . ->* . any))
|
|
. -> . any)
|
|
(lambda (get-pkg-info) ...)])
|
|
(values (or/c #f string?)
|
|
(listof module-path?)
|
|
any/c)]{
|
|
|
|
Gets information about the content of the package specified by
|
|
@racket[desc]. The information is determined inspecting the
|
|
package---resolving a @tech{package name}, downloading, and unpacking
|
|
into a temporary directory as necessary.
|
|
|
|
The results are as follows:
|
|
|
|
@itemize[
|
|
|
|
@item{The checksum, if any, for the downloaded package.}
|
|
|
|
@item{A list of module paths that are provided by the package.
|
|
Each module path is normalized in the sense of
|
|
@racket[collapse-module-path].}
|
|
|
|
@item{Information extracted from the package's metadata. By default,
|
|
this information is the package's dependencies, but in general
|
|
it is the result of @racket[extract-proc], which receives an
|
|
information-getting function (or @racket[#f]) as returned by
|
|
@racket[get-info].}
|
|
|
|
]}
|