8 Package Catalog Protocol

▼ |  | Package Management in Racket

1 | Getting Started with Packages
2 | Package Concepts
3 | Using raco pkg
4 | Package Metadata
5 | Source, Binary, and Built Packages
6 | Developing Packages with Git
7 | Package APIs
8 | Package Catalog Protocol
9 | PLane T Compatibility
10 | FAQ
11 | Future Plans
12 | How Package Installation and Distribution Works

► | 8 | Package Catalog Protocol

8.1 | Remote and Directory Catalogs
8.2 | SQLite Catalogs

On this page:

8.1 Remote and Directory Catalogs
8.2 SQLite Catalogs

8.18
top contents ← prev up next →

## 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.

top contents ← prev up next →