2d4f3e2ac9
The layer is now redundant, since everything left in "pkgs" is in the "racket-pkgs" category.
184 lines
6.7 KiB
Racket
184 lines
6.7 KiB
Racket
#lang scribble/manual
|
|
@(require (for-label racket/base
|
|
racket/contract/base
|
|
pkg/db
|
|
syntax/modcollapse
|
|
setup/dirs))
|
|
|
|
@title[#:tag "db"]{Package Catalog Database}
|
|
|
|
@defmodule[pkg/db]{The @racketmodname[pkg/db] library provides
|
|
tools for storing and retrieving @tech{package catalog}
|
|
information in a local database.}
|
|
|
|
The functions provided by @racketmodname[pkg/db] do not actually
|
|
manage packages; they do not change or consult the local database of
|
|
installed modules in any @tech{package scope}. The functions provided
|
|
by @racketmodname[pkg/db] simply reflect a local copy of the
|
|
information that a @tech{package catalog} and individual package
|
|
might provide (but with no guarantee of being in sync with an actual
|
|
@tech{package catalog} or package).
|
|
|
|
The database is implemented as an SQLite database with its own
|
|
locking, so no additional locks are needed for database access, but
|
|
beware of concurrent database changes that could break your program
|
|
logic.
|
|
|
|
@defstruct[pkg ([name string?]
|
|
[catalog string?]
|
|
[author string?]
|
|
[source string?]
|
|
[checksum string?]
|
|
[desc string?])
|
|
#:transparent]{
|
|
|
|
Represents a package implementation in the database. The @racket[name]
|
|
(@tech{package name}) and @racket[catalog] (@tech{package catalog},
|
|
normally a URL) fields are always nonempty
|
|
strings. Otherwise, unknown fields are represented by empty strings.}
|
|
|
|
|
|
@defparam[current-pkg-catalog-file file path-string?]{
|
|
|
|
A parameter that determines the file path used to hold the SQLite
|
|
database. The default value is in the user's add-on directory as
|
|
determined by @racket[(find-system-path 'addon-dir)] and within a
|
|
subdirectory determined by @racket[get-installation-name].}
|
|
|
|
|
|
@defproc[(call-with-pkgs-transaction [proc (-> any)]) any]{
|
|
|
|
Calls @racket[proc] so that multiple calls to other
|
|
@racketmodname[pkg/db] functions are grouped as a database
|
|
transaction, which avoids the overhead of making each individual call
|
|
its own transaction.
|
|
|
|
@history[#:added "6.1.1.5"]}
|
|
|
|
|
|
@deftogether[(
|
|
@defproc[(get-catalogs) (listof string?)]
|
|
@defproc[(set-catalogs! [catalogs (listof string?)]) void?]
|
|
)]{
|
|
|
|
Returns or sets the list of strings for all @tech{package catalog}
|
|
represented in the database. (Within the database, each
|
|
@tech{package catalog} gets its own identifying number.)
|
|
The order of indices in the list represents a search order.
|
|
|
|
The @racket[set-catalogs!] function removes information for any other
|
|
@tech{package catalogs} from the database.}
|
|
|
|
|
|
@defproc[(get-pkgs [#:name name (or/c #f string?) #f]
|
|
[#:catalog catalog (or/c #f string?) #f])
|
|
(listof pkg?)]{
|
|
|
|
Gets a list of package descriptions. If @racket[name] or
|
|
@racket[catalog] is not @racket[#f] (or if both are not @racket[#f]),
|
|
then the result includes only matching packages.
|
|
|
|
The result list is ordered by precedence of the @tech{package catalog}.}
|
|
|
|
|
|
@defproc[(set-pkgs! [catalog string?] [pkgs (listof (or/c string? pkg?))]
|
|
[#:clear-other-checksums? clear-other-checksums? #t])
|
|
void?]{
|
|
|
|
Sets the list of all packages that are recognized by the
|
|
@tech{package catalog} @racket[catalog].
|
|
|
|
Information about any other package for @racket[catalog] is removed from
|
|
the database. If a string is provided for @racket[pkgs], it is
|
|
treated as a package name; if additional information is already
|
|
recorded in the database for the package name, then the additional
|
|
information is preserved.
|
|
|
|
If @racket[clear-other-checksums?] is true, then for each element of
|
|
@racket[pkgs] that has a given checksum other than @racket[""], any
|
|
information in the database specific to another checksum (such as a
|
|
list of module paths) is removed from the database.}
|
|
|
|
|
|
@defproc[(set-pkg! [name string?]
|
|
[catalog string?]
|
|
[author string?]
|
|
[source string?]
|
|
[checksum string?]
|
|
[desc string?]
|
|
[#:clear-other-checksums? clear-other-checksums? (not (equal? checksum ""))])
|
|
void?]{
|
|
|
|
Sets the information for a specific package @racket[name] as
|
|
recognized by the @tech{package catalog} @racket[catalog].
|
|
|
|
If @racket[clear-other-checksums?] is true, then information (such as
|
|
a list of module paths) is removed from the database when it is
|
|
specific to a checksum other than @racket[checksum].}
|
|
|
|
|
|
@deftogether[(
|
|
@defproc[(get-pkg-tags [name string?] [catalog string?])
|
|
(listof string?)]
|
|
@defproc[(set-pkg-tags! [name string?] [catalog string?]
|
|
[module-paths (listof string?)])
|
|
void?]
|
|
)]{
|
|
|
|
Gets or sets a list of tags for the package
|
|
@racket[name] as recognized by the @tech{package catalog}
|
|
@racket[catalog].}
|
|
|
|
|
|
@deftogether[(
|
|
@defproc[(get-pkg-dependencies [name string?] [catalog string?] [checksum string?])
|
|
(listof list?)]
|
|
@defproc[(set-pkg-dependencies! [name string?] [catalog string?] [checksum string?]
|
|
[dependencies (listof any/c)])
|
|
void?]
|
|
)]{
|
|
|
|
Gets or sets a list of dependencies for the package
|
|
@racket[name] as recognized by the @tech{package catalog}
|
|
@racket[catalog] and for a specific @tech{checksum}.
|
|
|
|
The list of dependencies must have the shape described for a
|
|
@racket[deps] @filepath{info.rkt} field as described in
|
|
@secref["metadata"]. The result from @racket[get-pkg-dependencies] is
|
|
normalized: each dependency is represented by a list, a version in a
|
|
dependency is always preceded by @racket['#:version], and if both
|
|
version and platform specification are included, @racket['#:version]
|
|
appears before @racket['#:platform].}
|
|
|
|
|
|
@deftogether[(
|
|
@defproc[(get-pkg-modules [name string?] [catalog string?] [checksum string?])
|
|
(listof module-path?)]
|
|
@defproc[(set-pkg-modules! [name string?] [catalog string?] [checksum string?]
|
|
[module-paths (listof module-path?)])
|
|
void?]
|
|
)]{
|
|
|
|
Gets or sets a list of module paths that are provided for the package
|
|
@racket[name] as recognized by the @tech{package catalog}
|
|
@racket[catalog] and for a specific @tech{checksum}. The module paths
|
|
should be normalized in the sense of @racket[collapse-module-path].}
|
|
|
|
|
|
@defproc[(get-module-pkgs [module-path module-path?])
|
|
(listof pkg?)]{
|
|
|
|
Reports a list of packages that implement the given
|
|
@racket[module-path], which should be normalized in the sense of
|
|
@racket[collapse-module-path].}
|
|
|
|
|
|
@defproc[(get-pkgs-without-modules [#:catalog catalog (or/c #f string?) #f])
|
|
(listof pkg?)]{
|
|
|
|
Returns a list of packages (optionally constrained to @racket[catalog])
|
|
for which the database has no modules recorded.
|
|
|
|
Each resulting @racket[pkg] has its @racket[name], @racketidfont{catalog}, and
|
|
@racket[checksum] field set, but other fields may be @racket[""].}
|