fds-os/docs/software-format.md

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

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 is a complete example.

Custom sources are copied into srcpkgs/PACKAGE inside the selected writable build checkout. FDS uses .host/void-packages/; its vendor/void-packages/ submodule remains unchanged. The builder rejects a Git submodule as its build checkout. 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

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

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.

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.