4 Package Metadata

▼ |  | 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

Racket
top contents ← prev up next →

## 4 Package Metadata🔗ℹ

Package metadata, including dependencies on other packages, is reported by an "info.rkt" module within the package. This module must be implemented in the info language.

For example, a basic "info.rkt" file might be

> #lang info
> (define version "1.0")
> (define deps (list "base"))

The following "info.rkt" fields are used by the package manager:

> > > When a package is a single collection package, its "info.rkt" file may specify additional fields that are used for the Scribble documentation system or other tools. Many of these fields are described in Controlling raco setup with "info.rkt" Files.

- collection — either 'multi to implement a multi-collection package or a string or 'use-pkg-name to implement a single-collection package. If collection is defined as a string, then the string is used as the name of the collection implemented by the package. If collection is defined as 'use-pkg-name, then the package name is used as the package’s collection name.

  Beware that omitting collection or defining it as 'use-pkg-name means that a package’s content effectively changes with the package’s name. A package’s content should normally be independent of the package’s name, and so defining collection to a string is preferable for a single-collection package.

- version — a version string. The default version of a package is "0.0".

- deps — a list of dependencies, where each dependency has one of the following forms:

  - A string for a package source.

  - A list of the form

    > (list package-source-string
    > keyword-and-spec ...)

    where each keyword-and-spec has a distinct keyword in the form

    keyword-and-spec |  | = |  | '#:version version-string
    |  | | |  | '#:platform platform-spec
    platform-spec |  | = |  | string
    |  | | |  | symbol
    |  | | |  | regexp

    A version-string specifies a lower bound on an acceptable version of the needed package.

    A platform-spec indicates that the dependency applies only for platforms with a matching result from (system-type) when platforms-spec is a symbol or (system-type 'platform) when platform-spec is a string or regular expression. See also matching-platform?. For example, platform-specific binaries can be placed into their own packages, with one separate package and one dependency for each supported platform.

  - A list of the form

    > (list package-source-string version-string)

    which is deprecated and equivalent to

    > (list package-source-string '#:version version-string)

  Each element of the deps list determines a dependency on the package whose name is inferred from the package source (i.e., dependencies are on package names, not package sources), while the package source indicates where to get the package if needed to satisfy the dependency.

  Using the package name "racket" specifies a dependency on the Racket run-time system, which is potentially useful when a version is included in the dependency. For most purposes, it’s better to specify a versioned dependency on "base", instead.

  See also Package Dependency Checking.

- build-deps — like deps, but for dependencies that can be omitted from a binary package, which does not include sources; see Source, Binary, and Built Packages and Package Dependency Checking. The build-deps and deps lists are appended, while raco pkg create strips away build-deps when converting a package for --binary mode.

- implies — a list where each element is either a string or 'core. Each string refers to a package listed in deps and indicates that a dependency on the current package counts as a dependency on the named package; for example, the gui package is defined to ensure access to all of the libraries provided by gui-lib, so the "info.rkt" file of gui lists "gui-lib" in implies. Packages listed in implies list are treated specially by updating: implied packages are automatically updated whenever the implying package is updated. The special value 'core is intended for use by an appropriate base package to declare it as the representative of core Racket libraries.

- update-implies — a list of strings. Each string refers to a package listed in deps or build-deps and indicates that the implied packages are automatically updated whenever the implying package is updated.

- umbrella — a string for the name of an umbrella package, which is a package that should be considered the main representative for this package. An umbrella definition affects only the presentation of package lists and has no effect on installation. A package whose name is X-lib, X-doc, X-test, or X-exe is automatically treated as having an umbrella package X if such a package exists. A package has no umbrella if one is not inferred, no umbrella definition is present, or umbrella is defined as #f.

- setup-collects — a list of path strings and/or lists of path strings, which are used as collection names to set up via raco setup after the package is installed, or 'all to indicate that all collections need to be setup. By default, only collections included in the package are set up (plus collections for global documentation indexes and links).

- language-families — a list of strings naming language families for which the package is primarily of interest. The default is '("Racket"). If a package implements is own language, then it should declare the language only if multiple other packages (not under one umbrella package) are expected to also claim the language.

- license — a license S-expression specifying the package’s license. A license S-expression represents an SPDX license expression as a datum with the quoted form:

  license-sexp |  | = |  | license-id
  |  | | |  | (license-id WITH exception-id)
  |  | | |  | (license-sexp AND license-sexp)
  |  | | |  | (license-sexp OR license-sexp)

  > > > See further details below about license-id and the + operator.

  where:

  - a license-id is a short-form identifier from the SPDX License List, e.g. LGPL-3.0-or-later, Apache-2.0, or BSD-3-Clause; and

  - an exception-id is an identifier from the SPDX License Exceptions list, e.g. Classpath-exception-2.0.

  For example, packages in the main Racket distribution define license as:

  > (define license
  > '(Apache-2.0 OR MIT))

  The grammar of license S-expressions is designed so that (format "~s" license) produces a string conforming to the grammar in Annex D and Annex E of the SPDX Specification v2.2.2, which is specified in terms of character sequences.

  If the + operator is used, it must be written as part of the license-id, e.g. AFL-2.0+. Note that the SPDX Workgroup has deprecated (under “Allowing later versions of a license”) the use of the + operator with GNU licenses: thus, one writes AFL-2.0 or AFL-2.0+ but GPL-3.0-only or GPL-3.0-or-later (and neither GPL-3.0 nor GPL-3.0+ are correct).

- distribution-preference — either 'source, 'built, or 'binary, indicating the most suitable distribution mode for the package (but not a guarantee that it will be distributed as such). Absence of this definition implies 'binary if the package has no ".rkt" or ".scrbl" files other than "info.rkt" files, and if it has any ".so", ".dll", ".dylib", or ".framework" files; otherwise, absence implies 'built.

- package-content-state — a list of two items; the first item is 'binary, 'binary-lib, or 'built, and the second item is either #f or a string to represent a Racket version for compiled content. This information is used by raco pkg install or raco pkg update with --source, --binary, or --binary-lib to ensure that the package content is consistent with the requested conversion; see also Source, Binary, and Built Packages. Absence of this definition is treated the same as (list 'source #f).

- build-platforms — a list of strings describing platforms where the package should be expected to work. This declaration is intended for use by automated test and build systems, and it does not influence installation. A string matches when it corresponds to the result on the platform of (system-type), (system-type 'os*), (system-type 'arch), or a hyphenated combination of (system-type 'os*) and (system-type 'arch). The matching rules my be extended in the future to match additional strings. A build-platforms value of #f is the default, implying that the package is meant to build and pass its tests on all platforms.

Changed in version 6.1.0.5: Added update-implies.
Changed in version 6.1.1.6: Added distribution-preference.
Changed in version 8.2.0.7: Added license.
Changed in version 9.2.0.4: Added language-families, umbrella, and build-platforms.

top contents ← prev up next →