# 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.