c0bbfe8237
Fix error reporting so it's not an internal error. Also, report errors before printing a scope, and update the docs for earlier changes. Closes #1251
735 lines
31 KiB
Racket
735 lines
31 KiB
Racket
#lang scribble/manual
|
|
@(require "common.rkt"
|
|
(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
|
|
setup/matching-platform))
|
|
|
|
@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. It re-exports the bindings of @racketmodname[pkg/path].}
|
|
|
|
|
|
@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
|
|
(and/c path? complete-path?))]
|
|
@defparam[current-pkg-scope-version s string?]
|
|
)]{
|
|
|
|
Parameters that determine @tech{package scope} for management
|
|
operations and, in the case of @racket['user] scope, the relevant
|
|
installation name/version.}
|
|
|
|
@deftogether[(
|
|
@defparam[current-pkg-lookup-version s string?]
|
|
)]{
|
|
|
|
Parameter that determines the relevant Racket version for
|
|
extracting package information from a catalog.
|
|
|
|
@history[#:added "6.0.1.7"]}
|
|
|
|
|
|
@defparam[current-pkg-error err procedure?]{
|
|
|
|
A parameter whose value is used to report errors that are normally
|
|
intended for 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}.}
|
|
|
|
|
|
@deftogether[(
|
|
@defparam[current-pkg-download-cache-dir dir (or/c #f (and/c path-string? complete-path?))]
|
|
@defparam[current-pkg-download-cache-max-files max-files (or/c #f real?)]
|
|
@defparam[current-pkg-download-cache-max-bytes max-bytes (or/c #f real?)]
|
|
)]{
|
|
|
|
Parameters that determine the download cache location and limits. If
|
|
a parameter's value is @racket[#f], then the user's configuration is
|
|
used.}
|
|
|
|
|
|
@deftogether[(
|
|
@defparam[current-pkg-trash-max-packages max-packages (or/c #f real?)]
|
|
@defparam[current-pkg-trash-max-seconds max-seconds (or/c #f real?)]
|
|
)]{
|
|
|
|
Parameters that determine the trash-directory limits. If
|
|
a parameter's value is @racket[#f], then the user's configuration is
|
|
used.
|
|
|
|
@history[#:added "6.1.1.6"]}
|
|
|
|
|
|
@deftogether[(
|
|
@defparam[current-pkg-network-retries max-retries (or/c #f real?)]
|
|
)]{
|
|
|
|
A parameter that determines the number of times to retry a network communication
|
|
that fails due to a connection error. If
|
|
a parameter's value is @racket[#f], then the user's configuration is
|
|
used.
|
|
|
|
@history[#:added "6.3"]}
|
|
|
|
|
|
@defproc[(pkg-directory [name string?]
|
|
[#:cache cache (or/c #f (and/c hash? (not/c immutable?))) #f])
|
|
(or/c path-string? #f)]{
|
|
|
|
Returns the directory that holds the installation of the installed
|
|
(in any scope) package @racket[name], or @racket[#f] if no such package
|
|
is installed.
|
|
|
|
For multiple calls to @racket[pkg-directory], supply the same
|
|
@racket[equal?]-based mutable hash table (initially empty) as the
|
|
@racket[cache] argument. Otherwise, package-installation information
|
|
must be re-parsed on every call to @racket[pkg-directory].
|
|
|
|
@history[#:changed "6.1.1.6" @elem{Added the @racket[#:cache] argument.}]}
|
|
|
|
|
|
@defproc[(default-pkg-scope) (or/c 'installation 'user
|
|
(and/c path? complete-path?))]{
|
|
|
|
Returns the user's configured default @tech{package scope}.}
|
|
|
|
|
|
@defproc[(installed-pkg-names [#:scope scope (or/c #f 'installation 'user
|
|
(and/c path? complete-path?))])
|
|
(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
|
|
(and/c path? complete-path?))])
|
|
(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 [source string?]
|
|
[type (or/c #f 'name 'file 'dir 'link 'static-link
|
|
'file-url 'dir-url 'git 'github 'clone)]
|
|
[name (or/c string? #f)]
|
|
[checksum (or/c string? #f)]
|
|
[auto? boolean?]
|
|
[#:path path (or/c #f path-string?) #f])
|
|
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.
|
|
|
|
The optional @racket[path] argument is intended for use when
|
|
@racket[type] is @racket['clone], in which case it specifies a
|
|
directory containing the repository clone (where the repository itself
|
|
is a directory within @racket[path]).
|
|
|
|
@history[#:changed "6.1.1.1" @elem{Added @racket['git] as a @racket[type].}
|
|
#:changed "6.1.1.5" @elem{Added @racket['clone] as a @racket[type].}]}
|
|
|
|
|
|
@defproc[(pkg-stage [desc pkg-desc?]
|
|
[#:checksum checksum (or/c #f string?) #f]
|
|
[#:in-place? in-place? boolean? #f]
|
|
[#:namespace namespace namespace? (make-base-namespace)]
|
|
[#:strip strip (or/c #f 'source 'binary 'binary-lib) #f]
|
|
[#:force-strip? force-string? boolean? #f]
|
|
[#:use-cache? use-cache? boolean? #f]
|
|
[#:quiet? quiet? boolean? #t])
|
|
(values string? path? (or/c #f string?) boolean? (listof module-path?))]{
|
|
|
|
Locates the implementation of the package specified by @racket[desc]
|
|
and downloads and unpacks it to a temporary directory (as needed).
|
|
|
|
If @racket[desc] refers to an existing directory and
|
|
@racket[in-place?] is true, then the directory is used in place.
|
|
|
|
The @racket[namespace] argument is passed along to
|
|
@racket[get-info/full] when the package's @filepath{info.rkt} is
|
|
loaded.
|
|
|
|
If @racket[strip] is not @racket[#f], then files and directories are
|
|
removed from the prepared directory the same as when creating the
|
|
corresponding kind of package. A directory that is staged in-place
|
|
cannot be stripped. If @racket[force-strip?] is true, then a
|
|
consistency check (intended to avoid stripping a source package as
|
|
binary, for example) is skipped.
|
|
|
|
If @racket[use-cache?] is true, then a local cache is consulted before
|
|
downloading a particular package with a particular checksum. Note that
|
|
the default for @racket[use-cache?] is @racket[#f], while the default
|
|
is @racket[#t] for other functions that accept @racket[#:use-cache?].
|
|
|
|
The result is the package name, the directory containing the unpacked package content,
|
|
the checksum (if any) for the unpacked package, whether the
|
|
directory should be removed after the package content is no longer
|
|
needed, and a list of module paths provided by the package.}
|
|
|
|
|
|
@defproc[(pkg-config [set? boolean?] [keys/vals list?]
|
|
[#:from-command-line? from-command-line? boolean? #f])
|
|
void?]{
|
|
|
|
Implements @racket[pkg-config-command].
|
|
|
|
If @racket[from-command-line?] is true, error messages may suggest
|
|
specific command-line flags for @command-ref{config}.
|
|
|
|
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?]
|
|
[#:source source (or/c 'dir 'name)]
|
|
[#:mode mode (or/c 'as-is 'source 'binary 'binary-lib 'built)]
|
|
[#:dest dest-dir (or/c (and/c path-string? complete-path?) #f)]
|
|
[#:quiet? quiet? boolean? #f]
|
|
[#:from-command-line? from-command-line? boolean? #f])
|
|
void?]{
|
|
|
|
Implements @racket[pkg-create-command].
|
|
|
|
Unless @racket[quiet?] is true, information about the output is
|
|
reported to the current output port. If @racket[from-command-line?]
|
|
is true, error messages may suggest specific command-line flags for
|
|
@command-ref{create}.}
|
|
|
|
|
|
@defproc[(pkg-install [descs (listof pkg-desc?)]
|
|
[#:dep-behavior dep-behavior
|
|
(or/c #f 'fail 'force 'search-ask 'search-auto)
|
|
#f]
|
|
[#:update-deps? update-deps? boolean? #f]
|
|
[#:force? force? boolean? #f]
|
|
[#:ignore-checksums? ignore-checksums? boolean? #f]
|
|
[#:strict-doc-conflicts? strict-doc-conflicts? boolean? #f]
|
|
[#:use-cache? use-cache? boolean? #t]
|
|
[#:quiet? quiet? boolean? #f]
|
|
[#:use-trash? use-trash? boolean? #f]
|
|
[#:from-command-line? from-command-line? boolean? #f]
|
|
[#:strip strip (or/c #f 'source 'binary 'binary-lib) #f]
|
|
[#:force-strip? force-string? boolean? #f]
|
|
[#:multi-clone-mode multi-clone-mode (or/c 'fail 'force 'convert 'ask) 'fail]
|
|
[#:pull-mode pull-mode (or/c 'ff-only 'try 'rebase) 'ff-only]
|
|
[#:link-dirs? link-dirs? boolean? #f]
|
|
[#:dry-run? dry-run? boolean? #f])
|
|
(or/c 'skip
|
|
#f
|
|
(listof (or/c path-string?
|
|
(non-empty-listof path-string?))))]{
|
|
|
|
Implements @racket[pkg-install-command]. The result indicates which
|
|
collections should be setup via @exec{raco setup}: @racket['skip]
|
|
means that no setup is needed, @racket[#f] means all, and a list means
|
|
only the indicated collections.
|
|
|
|
The @racket[link-dirs?] argument determines whether package sources
|
|
inferred to be directory paths should be treated as links or copied
|
|
(like other package sources). Note that the default is @racket[#f],
|
|
unlike the default built into @racket[pkg-install-command].
|
|
|
|
A @racket[pkg-desc] can have the type @racket['clone] and a source
|
|
with the syntax of a package name, in which case it refers to a
|
|
@tech{package name} that must be mapped to a Git repository by the
|
|
@tech{package catalog}, and in will be installed as a clone.
|
|
|
|
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.
|
|
|
|
If @racket[from-command-line?] is true, error messages may suggest
|
|
specific command-line flags for @command-ref{install}.
|
|
|
|
The package lock must be held; see @racket[with-pkg-lock].
|
|
|
|
@history[#:changed "6.1.1.5" @elem{Added the @racket[#:multi-clone-mode]
|
|
and @racket[#:infer-clone-from-dir?] arguments.}
|
|
#:changed "6.1.1.6" @elem{Added the @racket[#:use-trash?] argument.}
|
|
#:changed "6.1.1.8" @elem{Added the @racket[#:pull-mode] argument.}
|
|
#:changed "6.4.0.14" @elem{Added the @racket[#:dry-run] argument.}]}
|
|
|
|
|
|
@defproc[(pkg-update [sources (listof (or/c string? pkg-desc?))]
|
|
[#:all? all? boolean? #f]
|
|
[#:dep-behavior dep-behavior
|
|
(or/c #f 'fail 'force 'search-ask 'search-auto)
|
|
#f]
|
|
[#:update-deps? update-deps? boolean? #f]
|
|
[#:force? force? boolean? #f]
|
|
[#:ignore-checksums? ignore-checksums? boolean? #f]
|
|
[#:strict-doc-conflicts? strict-doc-conflicts? boolean? #f]
|
|
[#:use-cache? use-cache? boolean? #t]
|
|
[#:skip-uninstalled? skip-uninstalled? boolean? #t]
|
|
[#:quiet? quiet? boolean? #f]
|
|
[#:use-trash? use-trash? boolean? #f]
|
|
[#:from-command-line? from-command-line? boolean? #f]
|
|
[#:strip strip (or/c #f 'source 'binary 'binary-lib) #f]
|
|
[#:force-strip? force-string? boolean? #f]
|
|
[#:lookup-for-clone? lookup-for-clone? boolean? #f]
|
|
[#:multi-clone-mode multi-clone-mode (or/c 'fail 'force 'convert 'ask) 'fail]
|
|
[#:pull-mode pull-mode (or/c 'ff-only 'try 'rebase) 'ff-only]
|
|
[#:link-dirs? link-dirs? boolean? #f]
|
|
[#:infer-clone-from-dir? infer-clone-from-dir? boolean? #f]
|
|
[#:dry-run? dry-run? boolean? #f])
|
|
(or/c 'skip
|
|
#f
|
|
(listof (or/c path-string?
|
|
(non-empty-listof path-string?))))]{
|
|
|
|
Implements @racket[pkg-update-command]. The result is the same as for
|
|
@racket[pkg-install].
|
|
|
|
A string in @racket[sources] refers to an installed package that should
|
|
be checked for updates. A @racket[pkg-desc] in @racket[sources]
|
|
indicates a package source that should replace the current
|
|
installation; as an exception, if a @racket[pkg-desc] has the type
|
|
@racket['clone] and a source with the syntax of a package name, it
|
|
refers to an existing package installation that should be converted to
|
|
a Git repository clone---unless @racket[lookup-for-clone?] is true,
|
|
in which case the package name is resolved through a catalog to
|
|
locate a Git repository clone.
|
|
|
|
The @racket[link-dirs?] and @racket[infer-clone-from-dir?] arguments
|
|
affect how directory paths in @racket[sources] are treated. The
|
|
@racket[link-dirs?] argument is propagated to
|
|
@racket[package-source->name+type], while
|
|
@racket[infer-clone-from-dir?] introduces a conversion from a
|
|
directory source to a repository-clone source when the directory
|
|
corresponds to an existing repository-clone installation.
|
|
|
|
If @racket[from-command-line?] is true, error messages may suggest
|
|
specific command-line flags for @command-ref{update}.
|
|
|
|
The package lock must be held; see @racket[with-pkg-lock].
|
|
|
|
@history[#:changed "6.1.1.5" @elem{Added the @racket[#:multi-clone-mode]
|
|
and @racket[#:infer-clone-from-dir?] arguments.}
|
|
#:changed "6.1.1.6" @elem{Added the @racket[#:use-trash?] argument.}
|
|
#:changed "6.1.1.8" @elem{Added the @racket[#:skip-uninstalled?] and @racket[#:pull-mode] arguments.}
|
|
#:changed "6.4.0.14" @elem{Added the @racket[#:dry-run] argument.}]}
|
|
|
|
|
|
@defproc[(pkg-remove [names (listof string?)]
|
|
[#:demote? demote? boolean? #f]
|
|
[#:auto? auto? boolean? #f]
|
|
[#:force? force? boolean? #f]
|
|
[#:quiet? quiet? boolean? #f]
|
|
[#:use-trash? boolean? use-trash? #f]
|
|
[#:from-command-line? from-command-line? boolean? #f]
|
|
[#:dry-run? dry-run? boolean? #f])
|
|
(or/c 'skip
|
|
#f
|
|
(listof (or/c path-string?
|
|
(non-empty-listof path-string?))))]{
|
|
|
|
Implements @racket[pkg-remove-command]. The result is the same as for
|
|
@racket[pkg-install], indicating collects that should be setup via
|
|
@exec{raco setup}.
|
|
|
|
If @racket[from-command-line?] is true, error messages may suggest
|
|
specific command-line flags for @command-ref{remove}.
|
|
|
|
The package lock must be held; see @racket[with-pkg-lock].
|
|
|
|
@history[#:changed "6.1.1.6" @elem{Added the @racket[#:use-trash?] argument.}
|
|
#:changed "6.4.0.14" @elem{Added the @racket[#:dry-run] argument.}]}
|
|
|
|
|
|
@defproc[(pkg-new [name path-string?])
|
|
(void?)]{
|
|
Implements @racket[pkg-new-command].
|
|
|
|
The @racket[name] parameter is the name of the new package.
|
|
}
|
|
|
|
|
|
@defproc[(pkg-show [indent string?]
|
|
[pkgs-or-patterns (or/c #f (listof string?))]
|
|
[#:prefix-line prefix-line (or/c #f string?) #f]
|
|
[#:auto? auto? boolean? #f]
|
|
[#:rx? rx? boolean? #f]
|
|
[#:long? long? boolean? #f]
|
|
[#:full-checksum? full-checksum? boolean? #f]
|
|
[#:directory show-dir? boolean? #f])
|
|
void?]{
|
|
|
|
Implements @racket[pkg-show-command] for a single package scope,
|
|
printing to the current output port. If @racket[prefix-line]s is not
|
|
@racket[#f], it is printed before the output. See also
|
|
@racket[installed-pkg-names] and @racket[installed-pkg-table].
|
|
|
|
If @racket[pkgs-or-patterns] is @racket[#f], then information is shown
|
|
for all installed packages, otherwise only matching packages are shown.
|
|
In @racket[rx?] is true, then elements of @racket[pkgs-or-patterns]
|
|
are treated as regular expression patterns, otherwise they are treated
|
|
as package names.
|
|
|
|
The package lock must be held to allow reads; see
|
|
@racket[with-pkg-lock/read-only].
|
|
|
|
@history[#:changed "6.1.1.5" @elem{Added the @racket[#:long?] argument.}
|
|
#:changed "6.1.1.6" @elem{Added the @racket[#:full-checksum?] and @racket[#:rx?] arguments.}
|
|
#:changed "6.5.0.1" @elem{Added the @racket[#:prefix-line] argument.}]}
|
|
|
|
|
|
@defproc[(pkg-migrate [from-version string?]
|
|
[#:dep-behavior dep-behavior
|
|
(or/c #f 'fail 'force 'search-ask 'search-auto)
|
|
#f]
|
|
[#:force? force? boolean? #f]
|
|
[#:use-cache? use-cache? boolean? #t]
|
|
[#:ignore-checksums? ignore-checksums? boolean? #f]
|
|
[#:strict-doc-conflicts? strict-doc-conflicts? boolean? #f]
|
|
[#:quiet? quiet? boolean? #f]
|
|
[#:from-command-line? from-command-line? boolean? #f]
|
|
[#:strip strip (or/c #f 'source 'binary 'binary-lib) #f]
|
|
[#:force-strip? force-string? boolean? #f]
|
|
[#:dry-run? dry-run? boolean? #f])
|
|
(or/c 'skip
|
|
#f
|
|
(listof (or/c path-string?
|
|
(non-empty-listof path-string?))))]{
|
|
|
|
Implements @racket[pkg-migrate-command]. The result is the same as for
|
|
@racket[pkg-install].
|
|
|
|
If @racket[from-command-line?] is true, error messages may suggest
|
|
specific command-line flags for @command-ref{migrate}.
|
|
|
|
The package lock must be held; see @racket[with-pkg-lock].
|
|
|
|
@history[#:changed "6.4.0.14" @elem{Added the @racket[#:dry-run] argument.}]}
|
|
|
|
|
|
@defproc[(pkg-catalog-show [names (listof string?)]
|
|
[#:all? all? boolean? #f]
|
|
[#:only-names? only-names? boolean? #f]
|
|
[#:modules? modules? boolean? #f])
|
|
void?]{
|
|
|
|
Implements @racket[pkg-catalog-show-command]. If @racket[all?] is true,
|
|
then @racket[names] should be empty.
|
|
|
|
The @racket[current-pkg-lookup-version] parameter determines the version
|
|
included in the catalog query.
|
|
|
|
@history[#:changed "6.0.1.7" @elem{Use @racket[current-pkg-lookup-version]
|
|
instead of @racket[current-pkg-scope-version].}]}
|
|
|
|
|
|
@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]
|
|
[#:relative-sources? relative-sources? boolean? #f])
|
|
void?]{
|
|
|
|
Implements @racket[pkg-catalog-copy-command].
|
|
|
|
The @racket[current-pkg-lookup-version] parameter determines the version
|
|
for extracting existing catalog information.
|
|
|
|
@history[#:changed "6.0.1.7" @elem{Use @racket[current-pkg-lookup-version]
|
|
instead of @racket[current-pkg-scope-version].}]}
|
|
|
|
|
|
@defproc[(pkg-catalog-archive [dest-dir path-string?]
|
|
[sources (listof path-string?)]
|
|
[#:from-config? from-config? boolean? #f]
|
|
[#:state-catalog state-catalog (or/c #f path-string?) #f]
|
|
[#:relative-sources? relative-sources? boolean? #f]
|
|
[#:quiet? quiet? boolean? #f]
|
|
[#:package-exn-handler package-exn-handler (string? exn:fail? . -> . any) (lambda (_pkg-name _exn) (raise _exn))])
|
|
void?]{
|
|
|
|
Implements @racket[pkg-catalog-archive-command].
|
|
|
|
The @racket[package-exn-handler] argument handles any exception that
|
|
is raised while trying to archive an individual package; the first
|
|
argument is the package name, and the second is the exception. The
|
|
default re-@racket[raise]s the exception, which aborts the archiving
|
|
process, while a function that logs the exception message and returns
|
|
would allow archiving to continue for other packages.
|
|
|
|
The @racket[current-pkg-lookup-version] parameter determines the version
|
|
for extracting existing catalog information.
|
|
|
|
@history[#:added "6.0.1.7"
|
|
#:changed "6.0.1.13" @elem{Added the @racket[#:package-exn-handler] argument.}]}
|
|
|
|
@defproc[(pkg-archive-pkgs [dest-dir path-string?]
|
|
[pkgs (listof path-string?)]
|
|
[#:include-deps? include-deps? boolean? #f]
|
|
[#:exclude exclude (listof string?) null]
|
|
[#:relative-sources? relative-sources? boolean? #f]
|
|
[#:quiet? quiet? boolean? #f]
|
|
[#:package-exn-handler package-exn-handler (string? exn:fail? . -> . any) (lambda (_pkg-name _exn) (raise _exn))])
|
|
void?]{
|
|
|
|
Implements @racket[pkg-archive-command].
|
|
|
|
The @racket[package-exn-handler] argument handles any exception that
|
|
is raised while trying to archive an individual package; the first
|
|
argument is the package name, and the second is the exception. The
|
|
default re-@racket[raise]s the exception, which aborts the archiving
|
|
process, while a function that logs the exception message and returns
|
|
would allow archiving to continue for other packages.
|
|
|
|
@history[#:added "6.1.0.8"]}
|
|
|
|
|
|
@defproc[(pkg-empty-trash [#:list? show-list? boolean? #f]
|
|
[#:quiet? quiet? boolean? #t])
|
|
void?]{
|
|
|
|
Implements @racket[pkg-empty-trash].
|
|
|
|
@history[#:added "6.1.1.6"]}
|
|
|
|
|
|
@defproc[(pkg-catalog-update-local [#:catalogs catalogs (listof string?) (pkg-config-catalogs)]
|
|
[#:catalog-file catalog-file path-string? (current-pkg-catalog-file)]
|
|
[#:quiet? quiet? boolean? #f]
|
|
[#:set-catalogs? set-catalogs? boolean? #t]
|
|
[#:consult-packages? consult-packages? boolean? #f])
|
|
void?]{
|
|
|
|
Consults the @tech{package catalogs} specified by @racket[catalogs] (in the
|
|
same way as @racket[pkg-catalog-copy]) and the user's configured 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.
|
|
|
|
The local catalog @racket[catalog-file] records the set of source catalogs,
|
|
including @racket[catalogs], from which its information is drawn. If
|
|
@racket[set-catalogs?] is true (which is the default), then
|
|
@racket[catalogs] is recorded as the set of sources, and information from any
|
|
other catalog is discarded. If @racket[set-catalogs?] is @racket[#f],
|
|
then @racket[catalogs] must be a subset of the source catalogs already
|
|
recorded in @racket[catalog-file].
|
|
|
|
@history[#:changed "6.0.1.6" @elem{Added @racket[#:catalogs] and @racket[#:set-catalogs?] arguments.}]}
|
|
|
|
|
|
@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-scopes) (listof (or/c 'installation 'user path?))]{
|
|
Obtains a list of all the currently-available package scopes.
|
|
|
|
@history[#:added "6.1.0.5"]}
|
|
|
|
@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[(pkg-single-collection [dir path-string?]
|
|
[#:name name string? @elem{... from @racket[dir] ...}]
|
|
[#:namespace namespace namespace? (make-base-namespapce)])
|
|
(or/c #f string?)]{
|
|
|
|
Returns a string for a collection name if @racket[dir] represents a
|
|
@tech{single-collection package}, or returns @racket[#f] if @racket[dir]
|
|
represents a @tech{multi-collection package}.
|
|
|
|
For some single-collection packages, the package's single collection
|
|
is the package name; if the package name is different from the
|
|
directory name, supply @racket[name].
|
|
|
|
Determining a single-collection package's collection name may require
|
|
loading an @filepath{info.rkt} file, in which case @racket[namespace]
|
|
is passed on to @racket[get-info/full].}
|
|
|
|
|
|
@defproc[(get-pkg-content [desc pkg-desc?]
|
|
[#:extract-info
|
|
extract-proc
|
|
((or/c #f
|
|
((symbol?) ((-> any)) . ->* . any))
|
|
. -> . any)
|
|
(lambda (get-pkg-info) ...)]
|
|
[#:namespace namespace namespace? (make-base-namespace)]
|
|
[#:use-cache? use-cache? boolean? #f]
|
|
[#:quiet? quiet? boolean? #t])
|
|
(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].}
|
|
|
|
]
|
|
|
|
The @racket[namespace] argument is effectively passed along to
|
|
@racket[get-info/full] and/or @racket[pkg-stage] for reading package
|
|
and collection @filepath{info.rkt} files.
|
|
|
|
The @racket[use-cache?] and @racket[quiet?] arguments are effectively
|
|
passed to @racket[pkg-stage] to control the use of a download cache
|
|
and status reporting.
|
|
|
|
@history[#:changed "6.1.1.2" @elem{Added the @racket[#:use-cache?] and
|
|
@racket[#:quiet?] arguments.}]}
|
|
|
|
|
|
@defproc[(extract-pkg-dependencies [info (symbol? (-> any/c) . -> . any/c)]
|
|
[#:build-deps? build-deps? boolean? #t]
|
|
[#:filter? filter? boolean? #f]
|
|
[#:versions? versions? boolean? #f])
|
|
(listof (or/c string? (cons/c string? list?)))]{
|
|
|
|
Returns packages dependencies reported by the @racket[info] procedure
|
|
(normally produced by @racket[get-info]).
|
|
|
|
If @racket[build-deps?] is true, then the result includes both
|
|
run-time dependencies and build-time dependencies.
|
|
|
|
If @racket[filter?] is true, then platform-specific dependencies are
|
|
removed from the result list when they do not apply to the current
|
|
platform, and other information is stripped so that the result list is
|
|
always a list of either strings (when @racket[versions?] is true) or a
|
|
two-element list containing a string and a version (when
|
|
@racket[versions?] is @racket[#f]).
|
|
|
|
@history[#:changed "6.0.1.6" @elem{Added the @racket[#:versions?] argument.}]}
|
|
|
|
|
|
@defproc[(pkg-directory->module-paths [dir path-string?]
|
|
[pkg-name string]
|
|
[#:namespace namespace namespace? (make-base-namespace)])
|
|
(listof module-path?)]{
|
|
|
|
Returns a list of module paths (normalized in the sense of
|
|
@racket[collapse-module-path]) that are provided by the package
|
|
represented by @racket[dir] and named @racket[pkg-name].}
|
|
|
|
|
|
@defproc[(pkg-directory->additional-installs [dir path-string?]
|
|
[pkg-name string]
|
|
[#:namespace namespace namespace? (make-base-namespace)]
|
|
[#:system-type sys-type (or/c #f symbol?) (system-type)]
|
|
[#:system-library-subpath sys-lib-subpath (or/c #f path-for-some-system?)
|
|
(system-library-subpath #f)])
|
|
(listof (cons/c symbol? string?))]{
|
|
|
|
Returns a list of pairs for items that are installed by the package
|
|
represented by @racket[dir] and named @racket[pkg-name]. Installed
|
|
items can include documentation, executables, foreign libraries, other
|
|
shared files, and man pages---all as specified by @filepath{info.rkt}
|
|
files. The symbol for each item gives it a category, such as
|
|
@racket['doc] or @racket['exe], and the string part is a normalized
|
|
name, such as the destination name for a document or a case-folded
|
|
executable name without a file suffix.
|
|
|
|
The @racket[sys-type] and @racket[sys-lib-subpath] arguments are used
|
|
in the same way as for @racket[matching-platform?] to determine
|
|
platform-specific installations as determined by
|
|
@racketidfont{install-platform} definitions in @filepath{info.rkt}
|
|
files.
|
|
|
|
@history[#:added "6.0.1.13"]}
|