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 (requires) — a string for a checksum.

  • 'name — a string that is the same as ‹package›.

  • 'author — a string for the author of the package, normally an e-mail address.

  • 'description — a string describing the package.

  • 'tags — a list of strings that describe the package’s categorization.

  • 'dependencies — a list of dependencies for the package, in the same shape as a deps "info.rkt" field as described in Package Metadata.

  • 'modules — 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).

• 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 (collection-file-path "pkg-catalog" "meta") directory of the full Racket distribution.

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.