108 lines
4.3 KiB
Markdown
108 lines
4.3 KiB
Markdown
# Software cartridge format
|
|
|
|
A PROGRAM cartridge is a complete GPT disk image with one EROFS metadata partition
|
|
and one or more EROFS payload partitions. New media uses catalogue format 2 and
|
|
stores installed Void package trees. Source recipes and build tools remain on
|
|
the workstation; FDS executes the installed files directly.
|
|
|
|
## Software source recipe
|
|
|
|
```toml
|
|
format = 2
|
|
id = "example.hello"
|
|
name = "Hello"
|
|
version = "1.0"
|
|
|
|
[commands]
|
|
hello = "usr/bin/hello"
|
|
|
|
[source]
|
|
package = "hello"
|
|
```
|
|
|
|
`package` names a source package in the selected `void-packages` checkout. For a
|
|
custom package, also set `template = "void"`: that directory must contain a
|
|
normal Void `template` and any `files/` or `patches/` directories it uses. Paths
|
|
are relative to this recipe. The [included hello package](../examples/software/hello/void/template)
|
|
is a complete example.
|
|
|
|
Custom sources are copied into an untracked `srcpkgs/PACKAGE` directory. Existing
|
|
tracked Void sources are never overwritten. If a generated source copy differs,
|
|
inspect it, preserve any independent edits, then remove that generated copy and
|
|
retry. An unchanged copy can be reused.
|
|
|
|
`fds-cartridge` builds with `xbps-src -a aarch64`, installs the resulting package
|
|
and runtime dependencies into a fresh tree, and records installed XBPS versions.
|
|
Use package dependency declarations to request runtime libraries and utilities.
|
|
Each software tree is self-contained with respect to its installed dependencies;
|
|
there is no cross-cartridge package resolver.
|
|
|
|
Software IDs and public command names use lowercase ASCII letters, digits,
|
|
periods, hyphens and underscores, with a maximum length of 64. Command paths are
|
|
relative to the installed root and must resolve to executable files within it.
|
|
|
|
## Cartridge recipe
|
|
|
|
```toml
|
|
format = 2
|
|
id = "example.tools"
|
|
name = "Example tools"
|
|
version = "1.0"
|
|
|
|
[[payload]]
|
|
sources = ["hello/software.toml", "report/software.toml"]
|
|
```
|
|
|
|
Each payload section creates one partition. Sources may be recipe paths or
|
|
previously built directories containing `software.toml` and `root/`. The metadata
|
|
partition records which software belongs to which partition. Software IDs and
|
|
cartridge identity must satisfy the metadata validation rules.
|
|
|
|
## On-disk contents
|
|
|
|
```text
|
|
Partition 1: FDS_METADATA
|
|
FDS/CARTRIDGE.TOML
|
|
FDS/SOFTWARE.TOML
|
|
Partition 2: FDS_PAYLOAD02
|
|
programs/example.hello/usr/bin/hello
|
|
programs/example.hello/usr/lib/...
|
|
programs/example.hello/var/db/xbps/...
|
|
programs/example.report/...
|
|
```
|
|
|
|
The software catalogue records identity, architecture, commands, partition,
|
|
installed package versions, entry count, byte count and SHA-256. `installed=true`
|
|
selects the direct-tree contract. The retained `unpacked_bytes` field records
|
|
installed file bytes; it does not imply an archive or guest extraction.
|
|
|
|
The tree digest covers sorted paths, entry types, modes, contents and symlink
|
|
targets. Root-relative package symlinks are relocated to relative in-tree links
|
|
when building. Escaping links, special files, privileged/writeable executable
|
|
trees, wrong-architecture ELF files and inconsistent metadata are rejected.
|
|
Current per-tree bounds are 1 GiB of file data and 65,536 entries.
|
|
|
|
## Runtime behavior
|
|
|
|
FDS verifies the cartridge's geometry, identity, inventory and tree integrity
|
|
on insertion. Payloads are mounted read-only with `nosuid,nodev`. No software
|
|
command runs automatically. Published command aliases appear in `/run/fds/bin`.
|
|
|
|
Programs run as UID/GID 1000 in the bay's managed process group. `FDS_APP` names
|
|
the installed tree; PATH, library paths and data search paths include its
|
|
`usr/bin`, `usr/lib` and `usr/share`. Dynamically linked ELF entry points use the
|
|
package tree's own loader. Programs that hard-code unrelated system paths still
|
|
need to be compatible with FDS; the tree is not a container or a writable root.
|
|
|
|
Safe eject stops consumers and releases every payload before reporting SAFE.
|
|
A digest detects corruption, not publisher identity: choose software sources
|
|
you trust. Distribution signatures are covered by [release verification](releases.md).
|
|
|
|
## Older media
|
|
|
|
The reader retains support for catalogue format 1 with xz payloads and legacy
|
|
single-partition PROGRAM cartridges containing `app/`. Old xz payloads retain
|
|
their temporary extraction behavior and limits. Creation commands produce only
|
|
the installed-tree format. Rebuild old software from its Void source recipe to
|
|
use direct execution.
|