1 Package Concepts

A package is a set of modules in some number of collections. Modules installed using the Racket package manager are required like any other modules. For example, if the package tic-tac-toe contains the module "matrix.rkt" in a "data" collection, then after tic-tac-toe is installed,

(require data/matrix)

imports the module. The package name is not mentioned with require, because packages are a way of managing library collections, not a way of referencing them. It is common, however, for a package to implement a collection whose name is the same as the package name—in which case a require might appear to be referencing a package, but it is actually referencing a collection provided by the package.

Each package has associated package metadata:

A package is typically represented by a directory with the same name as the package. The checksum is typically left implicit. The package directory can contain a file named "info.rkt" to declare other metadata (see Package Metadata).

A package source identifies a package representation. Each package source type has a different way of storing the checksum. The valid package source types are:

A package name resolver (PNR) is a server that converts package names to other package sources. A PNR is identified by a string representing a URL. This URL is combined with pkg/package› path segments (where ‹package› is a package name) plus a version=version› query (where ‹version› is the Racket version number) to form a URL that should refer to a read-able hash table with the keys: 'source mapped to the package source string and 'checksum mapped to the checksum value. Typically, the package source value for 'source will be a remote URL.

PLT supports two package name resolvers that are enabled by default: https://pkg.racket-lang.org for new packages and https://planet-compat.racket-lang.org for automatically generated packages for old PLaneT packages. Anyone may host their own package name resolver. The source for the PLT-hosted resolvers is in the (collection-file-path "pkg-index" "meta") directory.

After a package is installed, the original source of its installation is recorded, as well as if it was an automatic installation. An automatic installation is one that was installed because it was a dependency of a non-automatic installation package.

Two packages are in conflict if they contain the same module. For example, if the package tic-tac-toe contains the module file "data/matrix.rkt" and the package factory-optimize contains the module file "data/matrix.rkt", then tic-tac-toe and factory-optimize are in conflict. A package may also be in conflict with Racket itself, if it contains a module file that is part of the core Racket distribution. For example, any package that contains "racket/list.rkt" is in conflict with Racket. For the purposes of conflicts, a module is a file that ends in ".rkt" or ".ss".

Package A is a package update of Package B if (1) B is installed, (2) A and B have the same name, and (3) A’s checksum is different than B’s. Note that a package version is not taken into account when determining a package update, although a change in a package’s version (in either direction) implies a change in the checksum because the checksum is computed from the package source and the meta-data that specifies the version is part of the source.

A package scope determines the effect of package installations, updates, etc., with respect to different users, Racket versions, and Racket installations. The default package scope can be configured, but it is normally user, which is user-specific and version-specific; that is, package installation makes the package visible only for the installing user and with the installing version of Racket. The installation scope means that package installation makes the package visible to all users of the specific Racket installation that is used to install the package. Finally, the shared scope means user-specific, but for all versions and installations of Racket.