5.12 Internal Layout

3 min read

A package's tar entries divide into metadata entries under a reserved prefix and payload entries — the files that will be installed.

5.12.1 The reserved prefix #

Every metadata entry MUST appear under the path prefix .peipkg/ at the archive root. That prefix is reserved: a payload entry MUST NOT use any path beginning with .peipkg/, and no payload entry may be named literally .peipkg.

5.12.2 Required entries #

.peipkg/manifest.json and .peipkg/files.json MUST be present in every package. .peipkg/signature MUST be present in every signed package; a package without it is unsigned (§5.28).

5.12.3 Entry order #

Tar entries MUST appear in exactly this order:

1. .peipkg/manifest.json
2. .peipkg/files.json
3. Any optional metadata entries, sorted lexicographically by path
4. All payload entries, sorted lexicographically by path (§5.11 rule 1)
5. .peipkg/signature

The manifest comes first so that a streaming consumer can read a package's identity and reject a mismatched one — wrong name, wrong version, wrong architecture — before reading any payload.

The signature comes last because it signs everything preceding it (§5.28). A consumer MUST reject a package in which any named entry follows .peipkg/signature.

5.12.4 Optional metadata entries #

A package MAY carry additional entries under .peipkg/. The set this specification recognises is fixed at the three above; an unrecognised entry under .peipkg/ MUST be ignored on parse and MUST NOT prevent installation.

When present, an optional metadata entry MUST appear between .peipkg/files.json and the first payload entry.

5.12.5 Permitted entry types #

A payload entry MUST be one of:

• a regular file (typeflag 0 or \0)
• a directory (typeflag 5)
• a symbolic link (typeflag 2)

Any other entry type MUST cause the package to be rejected. This excludes hardlinks (typeflag 1), character devices (3), block devices (4), FIFOs (6), contiguous files (7), and every vendor-specific type.

Edit this page