221 lines
8.5 KiB
Racket
221 lines
8.5 KiB
Racket
#lang scribble/manual
|
|
@(require scribble/bnf
|
|
"common.rkt"
|
|
(for-label syntax/modcollapse))
|
|
|
|
@title[#:tag "catalog-protocol"]{Package Catalog Protocol}
|
|
|
|
A @tech{package catalog} is specified by a URL in one of three
|
|
forms:
|
|
|
|
@itemlist[
|
|
|
|
@item{@litchar{http://} or @litchar{https://} --- a remote URL}
|
|
|
|
@item{@litchar{file://} ending with @litchar{.sqlite} --- a local
|
|
SQLite database}
|
|
|
|
@item{@litchar{file://} without @litchar{.sqlite} --- a local
|
|
directory}
|
|
|
|
]
|
|
|
|
@section{Remote and Directory Catalogs}
|
|
|
|
In the case of a remote URL or a local directory naming a
|
|
@tech{package catalog}, the URL/path is extended as follows to obtain
|
|
information about packages:
|
|
|
|
@itemlist[
|
|
|
|
@item{@litchar{pkg} and @nonterm{package} path elements, where
|
|
@nonterm{package} is a @tech{package name}, plus a
|
|
@exec{version=}@nonterm{version} query (where @nonterm{version}
|
|
is a Racket version number) in the case of a remote URL.
|
|
|
|
This URL/path form is used to obtain information about
|
|
@nonterm{package}. An HTTP request for a remote URL should
|
|
respond with a @racket[read]-able hash table, as described
|
|
below. A path in a local directory formed by adding
|
|
@filepath{pkg} and @nonterm{package} should refer to a file
|
|
that similarly contains a @racket[read]-able hash table.
|
|
|
|
The hash table should supply the following keys:
|
|
|
|
@itemlist[
|
|
|
|
@item{@racket['source] (required) --- a @tech{package source}
|
|
string, typically a remote URL. If this source is a
|
|
relative URL, then it is treated as relative to the
|
|
catalog.
|
|
|
|
@history[#:changed "6.0.1.7" @elem{Added relative-path support
|
|
to clients of a catalog server.}]}
|
|
|
|
@item{@racket['checksum] (requires) --- a string for a
|
|
@tech{checksum}.}
|
|
|
|
@item{@racket['name] --- a string that is the same as
|
|
@nonterm{package}.}
|
|
|
|
@item{@racket['author] --- a string for the author of the
|
|
package, normally an e-mail address.}
|
|
|
|
@item{@racket['description] --- a string describing the
|
|
package.}
|
|
|
|
@item{@racket['tags] --- a list of strings that describe the
|
|
package's categorization.}
|
|
|
|
@item{@racket['dependencies] --- a list of dependencies for
|
|
the package, in the same shape as a @racket[deps]
|
|
@filepath{info.rkt} field as described in
|
|
@secref["metadata"].}
|
|
|
|
@item{@racket['modules] --- a list of module paths for modules
|
|
that are provided by the package; each module path should
|
|
be normalized in the sense of
|
|
@racket[collapse-module-path].}
|
|
|
|
@item{@racket['versions] (optional) --- a hash table mapping
|
|
version strings and @racket['default] to hash tables,
|
|
where each version-specific hash table provides mappings
|
|
to override the ones in the main hash table, and
|
|
@racket['default] applies to any version not otherwise
|
|
mapped.
|
|
|
|
Clients of a remote catalog may request information for
|
|
a specific version, but they should also check for a
|
|
@racket['versions] entry in a catalog response, in case
|
|
a catalog with version-specific mappings is implemented
|
|
as a directory or by a file-serving HTTP server. A
|
|
@racket['default] mapping, meanwhile, allows the main
|
|
hash table to provide information that is suitable for
|
|
clients at version 5.3.6 and earlier (which do not check
|
|
for @racket['versions]).}
|
|
|
|
]}
|
|
|
|
|
|
@item{@litchar{pkgs} path element: Obtains a list of package names
|
|
that are mapped by the @tech{package catalog}. An HTTP request for a remote URL
|
|
should respond with a @racket[read]-able list of strings. A
|
|
path in a local directory formed by adding @filepath{pkgs}
|
|
should refer to a file that similarly
|
|
contains a @racket[read]-able list of strings.
|
|
|
|
This URL/path form is used by @command-ref{catalog-copy} and
|
|
tools that allow a user to browse an catalog.
|
|
|
|
In the case of a local directory, if no @filepath{pkgs} file is
|
|
available, a list is created by listing all files in the
|
|
@filepath{pkg} directory.}
|
|
|
|
@item{@litchar{pkgs-all} path element: Obtains a hash table mapping
|
|
package names to package details. An HTTP request for a remote
|
|
URL should respond with a @racket[read]-able hash table mapping
|
|
strings to hash tables. A path in a local directory formed by
|
|
adding @filepath{pkgs-all} should refer to a
|
|
file that similarly contains a @racket[read]-able hash table.
|
|
|
|
This URL/path form is a shortcut for a @litchar{pkgs} URL/path
|
|
form combined with a @litchar{pkgs/}@nonterm{package} query for
|
|
each package.
|
|
|
|
In the case of a local directory, if no @filepath{pkgs-all}
|
|
file is available, a list is created from files in the
|
|
@filepath{pkg} directory.}
|
|
|
|
]
|
|
|
|
Note that a local directory served as files through an HTTP server
|
|
works as a remote URL, as long as the @filepath{pkgs} and
|
|
@filepath{pkgs-all} files are present (since those are optional for
|
|
local but required for HTTP).
|
|
|
|
The source for the PLT-hosted @tech{package catalog} is in the
|
|
@racket[(collection-file-path "pkg-catalog" "meta")]
|
|
directory of the full Racket distribution.
|
|
|
|
@; ----------------------------------------
|
|
|
|
@section{SQLite Catalogs}
|
|
|
|
A SQLite database @tech{package catalog} is meant to be constructed and queries
|
|
using the @racketmodname[pkg/db] library, but the database can be
|
|
constructed in any way as long as it contains the following tables:
|
|
|
|
@itemlist[
|
|
|
|
@item{A @tt{catalog} table with the format
|
|
|
|
@verbatim[#:indent 2]{(id SMALLINT,
|
|
url TEXT,
|
|
pos SMALLINT)}
|
|
|
|
Normally, the only row in this table is @tt{(0, "local", 0)},
|
|
but a database that records the content of a set of other
|
|
catalogs can also be used as an catalog, in which case each row
|
|
represents an catalog; the @tt{id} field is a unique identifier
|
|
for each catalog, the @tt{url} field is the catalog's URL, and the
|
|
@tt{pos} column orders the catalog relative to others (where a
|
|
lower @tt{pos} takes precedence).}
|
|
|
|
@item{A @tt{pkg} table with the format
|
|
|
|
@verbatim[#:indent 2]{(name TEXT,
|
|
catalog SMALLINT,
|
|
author TEXT,
|
|
source TEXT,
|
|
checksum TEXT,
|
|
desc TEXT)}
|
|
|
|
The @tt{catalog} field is normally @tt{0}; in the case that the
|
|
database reflects multiple other catalogs, the @tt{catalog} field
|
|
indicates the package entry's source catalog.
|
|
|
|
The @tt{pkg} and @tt{catalog} fields together determine a unique
|
|
row in the table.}
|
|
|
|
@item{A @tt{tags} table with the form
|
|
|
|
@verbatim[#:indent 2]{(pkg TEXT,
|
|
catalog SMALLINT,
|
|
tag TEXT)}
|
|
|
|
where the @tt{pkg} and @tt{catalog} combination identifies a unique
|
|
row in @tt{pkg}.}
|
|
|
|
@item{A @tt{modules} table with the form
|
|
|
|
@verbatim[#:indent 2]{(name TEXT,
|
|
pkg TEXT,
|
|
catalog SMALLINT,
|
|
checksum TEXT)}
|
|
|
|
where the @tt{pkg} and @tt{catalog} combination identifies a unique
|
|
row in @tt{pkg}, and @tt{name} is a printed module path.
|
|
|
|
This table is not currently used by any @exec{raco pkg}
|
|
command, but it can be used to suggest package installations to
|
|
provide a particular library.}
|
|
|
|
@item{A @tt{dependencies} table with the form
|
|
|
|
@verbatim[#:indent 2]{(onpkg TEXT,
|
|
onversion TEXT,
|
|
onplatform TEXT,
|
|
pkg TEXT,
|
|
catalog SMALLINT,
|
|
checksum TEXT)}
|
|
|
|
where the @tt{pkg} and @tt{catalog} combination identifies a unique
|
|
row in @tt{pkg}, and @tt{onpkg}, @tt{onversion}, and @tt{onplatform}
|
|
represent the dependency; @tt{onversion} or @tt{onplatform} is an
|
|
empty string if the dependency has no version or platform specification.
|
|
|
|
This table is not currently used by any @exec{raco pkg}
|
|
command.}
|
|
|
|
]
|