5.18 The Manifest

10 min read

The manifest is the authoritative metadata for a package: its identity, its relationships, its side-effect requirements, and its build provenance. It is a JSON document at .peipkg/manifest.json.

5.18.1 Schema #

{
  "schema_version": 1,
  "name": "<string>",
  "version": "<string>",
  "architecture": "<string>",
  "description": "<string>",
  "license": "<string>",
  "license_class": "<string>",
  "homepage": "<string>",
  "default_root": "<root reference>",
  "special_system_package": <bool>,
  "alternate_upgrade": {<alternate_upgrade>},
  "dependencies": [<dependency>...],
  "optional_dependencies": [<dependency>...],
  "conflicts": [<dependency>...],
  "provides": [<provides>...],
  "replaces": [<replaces>...],
  "side_effects": [<string>...],
  "size_installed": <integer>,
  "sd_overrides": [<sd_override>...],
  "build": {<build>}
}

5.18.2 Required fields #

A manifest missing any required field MUST be rejected.

The package format treats name as an opaque canonical identifier within the §5.3 grammar; it does not derive or authenticate namespace ownership. Peios catalogues assign reverse-DNS names whose leading segments identify the upstream namespace and whose final segment is the familiar package name, such as com.amd.amd-ucode. Peios-originated packages use org.peios. Dependency and package-operation inputs that identify a concrete package carry the complete canonical name; virtual capabilities retain their own names. Repository signatures and build provenance, rather than the spelling of name, establish who produced a particular package.

5.18.3 Optional fields #

A manifest carrying an unknown field MUST NOT be rejected; the unknown field MUST be ignored (§5.9).

5.18.4 The alternate_upgrade object #

{
  "message": "<string>"
}

A package that sets alternate_upgrade states that it is meant to be installed and upgraded by some means other than a routine package operation — an operating-system edition moved by a dedicated tool that also reconciles what the package manager deliberately does not touch, for example. The package manager grants nothing on the declaration's behalf. Its whole effect is on the consumer:

1. A request that names the package — install or upgrade with the package as an argument — or any install or named-upgrade plan whose operations would install or upgrade the package as a dependency, MUST be refused: nothing is applied, and the consumer MUST report the package's name, its message verbatim, and this warning:

   Alternate upgrade paths may bypass normal peipkg protections; ensure you fully trust the authors of the package before running.

2. An upgrade of every installed package MUST hold the package back at its installed version, report it as in rule 1, and proceed with the rest of the upgrade. Holding back is not a failure.

3. A consumer MUST provide a deliberate, per-invocation override (--bypass-alternate-upgrade in the reference implementation) under which rules 1 and 2 do not apply. The override is the intended way for the out-of-band tool to drive the package manager; it is never a default and is never persisted.

Composing a root from nothing — an image builder populating an empty tree, rather than a consumer changing an installed system — is not an install or upgrade in the sense above, and an image builder MUST ignore the field.

5.18.5 The build object #

{
  "timestamp": "<RFC 3339 timestamp>",
  "farm_id": "<string>",
  "source_ref": "<string>"
}

A consumer MUST treat an absent optional field as the empty value.

timestamp is also the modification time of every tar entry (§5.11 rule 2). A producer MUST set both identically.

source_ref is producer-defined but SHOULD be a machine-resolvable reference. The conventional form is a version-control URL with an explicit ref:

git+https://git.peios.org/sources/nginx#refs/tags/v1.26.2-3

5.18.6 Field constraints #

description, when present, MUST consist only of printable ASCII in the range 0x20–0x7E. ASCII control characters and non-ASCII bytes MUST NOT appear. It SHOULD be a single line under 80 characters; longer descriptions belong in upstream documentation.

license, when present, SHOULD be a valid SPDX expression. A producer MAY use another form; this specification does not validate license strings. A LicenseRef- term names a licence with no SPDX identifier; a producer using one SHOULD ship the licence text under /usr/share/licenses/<name>/ in the same package.

license_class, when present, MUST be one of unknown, free, firmware, or proprietary; any other value MUST cause the package to be rejected. Absent means unknown, and a consumer MUST treat the two identically. A producer SHOULD declare a class other than unknown whenever license contains a LicenseRef- term, since that is precisely the case in which the expression alone cannot say.

homepage, when present, MUST be a syntactically valid URL per RFC 3986 and MUST use the https or http scheme. Any other scheme MUST cause the package to be rejected.

size_installed MUST be a non-negative integer, and MUST equal the sum of the size fields of every entry in the files manifest (§5.25). A consumer MUST verify that equality and MUST reject a package where it does not hold.

5.18.7 Authoritative status #

The manifest is authoritative for a package's metadata. Where it disagrees with any other source — the repository index, the filename, secondary documentation — the manifest MUST be treated as correct, and the disagreement MUST be reported (§5.32).

5.18.8 Encoding #

The manifest MUST be UTF-8 encoded JSON and MUST end with a single newline.

A producer that intends its packages to be byte-reproducible MUST serialise the manifest canonically: compact, with no insignificant whitespace, with HTML-escaping of <, >, and & disabled, with fields in the declaration order of the schema above, and with every optional field either always emitted or never emitted for a given producer.

Edit this page