fds-os/docs/README.md

Documentation guide

FDS/OS builds bootable ARM SYSTEM images, an internal NVMe disk, independent recovery, and a development environment. Native s6 manages the base system, including Dasung support; cartridge tools manage DATA, programs and optional desktop/network activation. M0–M12 software checks and local release verification have passed. Physical Pi validation is deferred. The guides below explain how to build, use and test the implemented system.

If this is your first visit

1. Read the project overview for the intended computer and current capabilities.
2. Follow Your first build to create and inspect the working artifacts.
3. Read Architecture to understand the relationship between the build host, Linux packages, FDS tools, and cartridges.
4. Use the Development guide for subsequent changes and rebuilds.

The Glossary explains terms such as ABI, sysroot, EROFS, and masterdir. No prior Void or s6 experience is assumed by the first-build guide.

Working with the repository today

Guide	Question it answers
Workstation and emulator	How do I build software, create a 1+m cartridge image, boot FDS, insert/remove it and write USB?
Software cartridge format	What goes in metadata, payload partitions and xz tarballs, and how does the guest run them?
Workstation validation	Which host builds, whole-image writes and public QEMU lifecycle tests actually passed?
Your first build	What do I install, what do I run, and how do I know it worked?
M1 root filesystem	How do I build the OS filesystem, run its ARM shell, inspect packages, and test the archive?
FDS Rust tooling	How do I build and run the static FDS command and boot-discovery tools?
Clap migration validation	Which parser, complete-image, VM and startup checks passed after standardizing the Rust command lines?
Internal storage	How do I build the full NVMe disk, persist bay settings and save diagnostics?
Release signatures	How do I create a signing key, sign artifacts and verify a download with a trusted key?
Frozen inputs and offline rebuilds	How do I preserve inputs, build without network access, compare results and assemble a local release?
Boot images	How do I create the Pi boot partition, initramfs and SYSTEM cartridge, and test insertion/recovery?
Desktop, PROGRAM and Ethernet	How do I start WindowMaker, run cartridge programs, and enable networking?
Media tools	How are images created, inspected and confirmed before cartridge writes?
Pi 5 EEPROM configuration	How do I prepare, review and restore bootloader settings without flashing the build host?
Twelve-bay stress tests	How do I run the twelve-device VM checks and prepare physical tests?
Shutdown and reboot	How does shutdown protect DATA, and what should I do when it is blocked?
Writable DATA	Where do user files live, how do managed programs work, and when is removal safe?
Implementation through M12	What is complete, pending, and deferred to physical hardware?
M12 software evidence	Which checks, offline comparisons and signed local artifacts establish M12 software acceptance?
Native init and ARM VM	How do I boot the system, open its shell, and start or stop a service?
M1 validation	What did the original rootfs milestone verify?
M2 validation	Which full ARM boot and service-control checks passed?
M3 validation	Which static tooling and ARM parsing/discovery checks passed?
M4 software validation	Which image, module, stage0, insertion and recovery tests passed?
M5 software validation	Which ordinary-console, trace, emulation and optimization checks passed?
M6 software validation	Which virtual USB, mapping, metadata, mount, IPC and eject checks passed?
M7 DATA validation	Did sustained writes survive safe eject, reinsertion and independent filesystem checks?
M8 desktop/network validation	Did desktop transitions, PROGRAM execution, fonts and Ethernet work in the ARM VM?
M9 media-tool validation	Did ARM image creation, confirmed cartridge writes, verification and boot of a newly written SYSTEM pass?
M10 shutdown validation	Which ordered halt/reboot, busy refusal, crash and writeback-error tests passed?
M11 stress validation	Which twelve-device and media failure tests have passed, and what remains?
Build host reference	Which versions, dependencies, environment settings, and checks does the pipeline use?
Development	How do I rebuild only the component I changed, configure the build, and prepare a change?
Dasung monitor	How is the existing monitor daemon built, packaged, configured, and tested for the base system?
Dasung validation	Which builds, simulator cases, and native s6 checks actually passed?
Packages	What is an XBPS package, and how do I inspect the one I built?
Troubleshooting	Why did a command fail, and what should I check next?
M0 validation	What has actually been built and verified on the development host?

Understanding the operating system

These pages explain the implemented behavior and distinguish software evidence from properties that still need physical hardware tests.

Guide	Subject
Architecture	Machine model, two library strategies, host/target split, writable state
Boot	From internal NVMe to a removable SYSTEM and the first console
Cartridges	Cartridge classes, physical bays, insertion, ejection, and manifests
Services	Native s6, service dependencies, readiness, and shutdown
Performance	Timing targets, measurement boundaries, and regression reporting
Recovery	Build and enter independent recovery, inspect cartridges, check/repair DATA and prepare replacement SYSTEM media

Planning and reference

• Roadmap: current milestone, remaining milestones, and acceptance criteria.
• Master plan: the complete 67-section specification; examples describe the final design unless stated otherwise.
• Project instructions: implementation scope and conventions.

A sh code block in a current-workflow guide is intended to be run from the repository root unless the surrounding text says otherwise. Planned runtime examples use text blocks and are labeled as future behavior. Run build commands sequentially; they share one Void build directory.