fds-os/docs/developer/void-workspace.md

Clean upstream and writable Void workspace

FDS keeps upstream source separate from its build state:

Path	Ownership and purpose
vendor/void-packages/	Clean upstream Git submodule at VOID_PACKAGES_COMMIT
packages/	Authoritative FDS base-package sources, including Dasung
examples/software/*/void/	Authoritative example PROGRAM package sources
.host/void-packages/	Generated writable checkout, package copies, local configuration, caches and build container

make bootstrap creates the build checkout locally at the pinned commit. It copies Git objects independently; there is no network fetch for this step, no Git alternates dependency and no hardlinks into the upstream source. Normal package bootstrap still uses its configured repositories.

tools/prepare-void copies FDS package overlays into the writable checkout and retains the existing checks against replacing upstream packages or overwriting changed generated copies. Workstation builds default to the same checkout. Explicitly selecting a Git submodule with --void-packages is rejected before source files or build state can be written there.

The workspace helper migrates old, matching generated files and build caches by renaming them. It compares every file, mode and symlink in each known source copy first. Unknown upstream files, staged changes, independent edits and conflicting destinations stop migration. Run builds and migration sequentially. The workspace lock prevents two preparations from changing the layout together. Python is already a build-host prerequisite; this introduces no new dependency.

For this checkout, the 58 staged additions matched the main-repository sources. Their local commit 47580322e801ef195c9bf279fd1fe4d8a1f723e9 and both staged patches were saved under .host/backups/void-overlays-20260922-134611/ before unstaging those copies. The parent gitlink was restored to upstream commit 02a3cbc132c3c4a3a9d59e9b98f517af5dd11cd1, matching the declared pin. All eleven package directories, hostdir, masterdir-x86_64 and etc/conf were moved into the build checkout. No upstream tracked source was changed.

An explicit future pin update advances the writable checkout without replacing its caches. Git refuses updates that would overwrite local files. Continue to record the parent gitlink and VOID_PACKAGES_COMMIT together.

Frozen-input creation uses the separate build checkout. New restores recreate that layout. Older saved projects retain their original layout and scripts; the frozen 0.1.0 release is untouched. Restore compatibility tests do not imply a new reproducibility or physical-hardware claim.

Validation

Fresh checks for this change passed:

• make bootstrap, make smoke-test, and make check: migrated container use, ARM/glibc package compilation, static-musl compilation, clean upstream state, exact overlay/cache preservation, shallow pin updates, rejection of independent edits and source conflicts, and cleanup protections.
• make workstation-test: out/workstation-images.ckkodex6; real Void source builds from .host/void-packages, image validation and confirmed file write/readback. Selecting the upstream submodule as a build target is rejected without writes.
• make emulator-test: out/emu-test.op5azhlm; full twelve-bay PROGRAM/DATA, foreground terminal, eject/unplug, legacy reading and service-restart checks.
• make release-contract-test: out/m12-release-contracts.wmsfrcl0; both separate and legacy frozen-layout restores, retained source caches, local offline repositories and existing tamper/release-comparison checks.
• Documentation links, formatting, Python syntax and a final empty upstream Git status, including ignored files, were checked.

Logs are in out/logs/void-workspace/; source and log hashes, pins, native binary hashes and fixture results are recorded in out/manifests/void-workspace-acceptance.json. The optional host-native ARM execution shortcut was skipped in smoke-test. ARM execution was exercised by the full emulator suite. Physical hardware was not used.

The first emulator attempt (out/emu-test.463emq8u) failed on an empty cartridge IPC response during initial discovery in its admin VM. The complete rerun passed without target-system changes. SYSTEM, kernel and initramfs hashes matched the previous accepted inputs. The cause of that first response failure was not established; its command/serial logs are retained. Future failures now collect live service diagnostics before VM shutdown, without retrying failed commands or relaxing their acceptance conditions.