134 lines
5.2 KiB
Racket
134 lines
5.2 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 "path"]{Package Paths and Database}
|
|
|
|
@defmodule[pkg/path]{The @racketmodname[pkg/path] library provides
|
|
utilities for working with package paths and installed-package
|
|
databases.}
|
|
|
|
@defstruct*[pkg-info ([orig-pkg (or/c (list/c 'catalog string?)
|
|
(list/c 'catalog string? string?)
|
|
(list/c 'url string?)
|
|
(list/c 'file string?)
|
|
(list/c 'dir string?)
|
|
(list/c 'link string?)
|
|
(list/c 'static-link string?)
|
|
(list/c 'clone string? string?))]
|
|
[checksum (or/c #f string?)]
|
|
[auto? boolean?])
|
|
#:prefab]{
|
|
|
|
A structure type that is used to report installed-package information.
|
|
|
|
The @racket[orig-pkg] field describes the source of the package as
|
|
installed, where @racket['catalog] refers to a package that was
|
|
installed by consulting a catalog with a package name, and so on. The
|
|
two-element @racket['catalog] form records a URL for a Git or GitHub
|
|
package source when the catalog reported such a source, and the URL is
|
|
used for operations that adjust @racket['clone]-form installations.
|
|
|
|
@history[#:changed "6.1.1.5" @elem{Added @racket['clone] and two-level
|
|
@racket['catalog] variants for
|
|
@racket[orig-pkg].}]}
|
|
|
|
|
|
@defstruct*[(sc-pkg-info pkg-info) ()]{
|
|
|
|
A structure subtype that represents a package that is installed as
|
|
single-collection.}
|
|
|
|
@deftogether[(
|
|
@defstruct*[(pkg-info/alt pkg-info) ([dir-name string?])]
|
|
@defstruct*[(sc-pkg-info/alt sc-pkg-info) ([dir-name string?])]
|
|
)]{
|
|
|
|
Structure subtypes that are used when the installation directory for a
|
|
package does not match the package name, but is instead
|
|
@racket[dir-name]. The directory name always includes a @litchar{+}
|
|
(which is disallowed in a package name).}
|
|
|
|
|
|
@defproc[(path->pkg [path path-string?]
|
|
[#:cache cache (or/c #f (and/c hash? (not/c immutable?)))])
|
|
(or/c string? #f)]{
|
|
|
|
Returns the installed package containing @racket[path], if any.
|
|
|
|
If @racket[cache] is not @racket[#f], then it is consulted and
|
|
modified to cache installed-package information across calls to
|
|
@racket[path->pkg] (with the assumption that the set of installed
|
|
packages does not change across calls that receive the same
|
|
@racket[cache]).}
|
|
|
|
|
|
@defproc[(path->pkg+subpath [path path-string?]
|
|
[#:cache cache (or/c #f (and/c hash? (not/c immutable?)))])
|
|
(values (or/c string? #f) (or/c path? 'same #f))]{
|
|
|
|
Like @racket[path->pkg], but returns a second value that represents
|
|
the remainder of @racket[path] within the package's directory.}
|
|
|
|
|
|
@defproc[(path->pkg+subpath+scope [path path-string?]
|
|
[#:cache cache (or/c #f (and/c hash? (not/c immutable?)))])
|
|
(values (or/c string? #f)
|
|
(or/c path? 'same #f)
|
|
(or/c 'installation 'user (and/c path? complete-path?) #f))]{
|
|
|
|
Like @racket[path->pkg+subpath], but returns a third value for the package's
|
|
installation scope.}
|
|
|
|
|
|
@defproc[(path->pkg+subpath+collect [path path-string?]
|
|
[#:cache cache (or/c #f (and/c hash? (not/c immutable?)))])
|
|
(values (or/c string? #f) (or/c path? 'same #f) (or/c string? #f))]{
|
|
|
|
Like @racket[path->pkg+subpath], but returns a third value for a
|
|
collection name if the package is a single-collection package,
|
|
@racket[#f] otherwise.}
|
|
|
|
|
|
@defproc[(path->pkg+subpath+collect+scope [path path-string?]
|
|
[#:cache cache (or/c #f (and/c hash? (not/c immutable?)))])
|
|
(values (or/c string? #f)
|
|
(or/c path? 'same #f)
|
|
(or/c string? #f)
|
|
(or/c 'installation 'user (and/c path? complete-path?) #f))]{
|
|
|
|
Like @racket[path->pkg+subpath+collects], but returns a fourth value for
|
|
the package's installation scope.}
|
|
|
|
|
|
@defproc[(get-pkgs-dir [scope (or/c 'installation 'user 'shared
|
|
(and/c path? complete-path?))]
|
|
[user-version string? (version)])
|
|
path?]{
|
|
|
|
Returns the path of the directory that holds installed packages in the
|
|
given scope. The @racket[user-version] argument is used to generate
|
|
the result for @racket['user] scope.}
|
|
|
|
|
|
@defproc[(read-pkgs-db [scope (or/c 'installation 'user 'shared
|
|
(and/c path? complete-path?))])
|
|
(hash/c string? pkg-info?)]{
|
|
|
|
Returns a hash table representing the currently installed packages
|
|
in the specified scope.}
|
|
|
|
|
|
@defproc[(read-pkg-file-hash [path path?]) hash?]{
|
|
|
|
Reads a hash table from @racket[path], logging any errors and
|
|
returning an empty hash table if @racket[path] does not exist or if an
|
|
error is encountered.}
|