8 Package Catalog Protocol
A package catalog is specified by a URL in one of three forms:
http:// or https:// —
a remote URL file:// ending with .sqlite —
a local SQLite database file:// without .sqlite —
a local directory
8.1 Remote and Directory Catalogs
In the case of a remote URL or a local directory naming a package catalog, the URL/path is extended as follows to obtain information about packages:
pkg and ‹package› path elements, where ‹package› is a package name, plus a version=‹version› query (where ‹version› is a Racket version number) in the case of a remote URL.
This URL/path form is used to obtain information about ‹package›. An HTTP request for a remote URL should respond with a read-able hash table, as described below. A path in a local directory formed by adding "pkg" and ‹package› should refer to a file that similarly contains a read-able hash table.
The hash table should supply the following keys:
'source (required) —
a package source string, typically a remote URL. If this source is a relative URL, then it is treated as relative to the catalog. Changed in version 6.0.1.7: Added relative-path support to clients of a catalog server.
'checksum (required) —
a string for a checksum. 'name (optional) —
a string that is the same as ‹package›. 'author (optional) —
a string for the author of the package, normally an e-mail address. 'description (optional) —
a string describing the package. 'tags (optional) —
a list of strings that describe the package’s categorization. 'dependencies (optional) —
a list of dependencies for the package, in the same shape as a deps "info.rkt" field as described in Package Metadata. 'modules (optional) —
a list of module paths for modules that are provided by the package; each module path should be normalized in the sense of collapse-module-path. 'versions (optional) —
a hash table mapping version strings and 'default to hash tables, where each version-specific hash table provides mappings to override the ones in the main hash table, and '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 '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 '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 'versions).
'ring (optional) —
either #f or a ring number. See get-pkg-ring for more information.
pkgs path element: Obtains a list of package names that are mapped by the package catalog. An HTTP request for a remote URL should respond with a read-able list of strings. A path in a local directory formed by adding "pkgs" should refer to a file that similarly contains a read-able list of strings.
This URL/path form is used by raco pkg catalog-copy and tools that allow a user to browse an catalog.
In the case of a local directory, if no "pkgs" file is available, a list is created by listing all files in the "pkg" directory.
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 read-able hash table mapping strings to hash tables. A path in a local directory formed by adding "pkgs-all" should refer to a file that similarly contains a read-able hash table.
This URL/path form is a shortcut for a pkgs URL/path form combined with a pkgs/‹package› query for each package.
In the case of a local directory, if no "pkgs-all" file is available, a list is created from files in the "pkg" directory.
Note that a local directory served as files through an HTTP server works as a remote URL, as long as the "pkgs" and "pkgs-all" files are present (since those are optional for local but required for HTTP).
The source for the PLT-hosted package catalog is in the pkg-index package.
8.2 SQLite Catalogs
A SQLite database package catalog is meant to be constructed and queries using the pkg/db library, but the database can be constructed in any way as long as it contains the following tables:
A catalog table with the format
(id SMALLINT,
url TEXT,
pos SMALLINT)
Normally, the only row in this table is (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 id field is a unique identifier for each catalog, the url field is the catalog’s URL, and the pos column orders the catalog relative to others (where a lower pos takes precedence).
A pkg table with the format
(name TEXT,
catalog SMALLINT,
author TEXT,
source TEXT,
checksum TEXT,
desc TEXT)
The catalog field is normally 0; in the case that the database reflects multiple other catalogs, the catalog field indicates the package entry’s source catalog.
The pkg and catalog fields together determine a unique row in the table.
A tags table with the form
(pkg TEXT,
catalog SMALLINT,
tag TEXT)
where the pkg and catalog combination identifies a unique row in pkg.
A modules table with the form
(name TEXT,
pkg TEXT,
catalog SMALLINT,
checksum TEXT)
where the pkg and catalog combination identifies a unique row in pkg, and name is a printed module path.
This table is not currently used by any raco pkg command, but it can be used to suggest package installations to provide a particular library.
A dependencies table with the form
(onpkg TEXT,
onversion TEXT,
onplatform TEXT,
pkg TEXT,
catalog SMALLINT,
checksum TEXT)
where the pkg and catalog combination identifies a unique row in pkg, and onpkg, onversion, and onplatform represent the dependency; onversion or onplatform is an empty string if the dependency has no version or platform specification.
This table is not currently used by any raco pkg command.
A ring table with the form
(pkg TEXT,
catalog SMALLINT,
ring SMALLINT)
where the pkg and catalog combination identifies a unique row in pkg.
Added in version 6.10.0.3.