fds-os/docs/cleanup.md

Reclaim build space

Run these from the repository root after stopping builds and test VMs:

make clean-preview
make clean

The preview lists every selected directory, its combined allocated footprint, and the generated directories being kept. It does not delete files. make clean recalculates the selection and deletes it without a confirmation prompt. Repeat it whenever old build/test workspaces accumulate. It needs Python 3, Git and GNU du, already used by the build host; it needs no Rust compilation, downloads, root privileges or new Python packages.

What is removed

• Old generated rootfs, kernel, initramfs, SYSTEM, boot, recovery and internal image workspaces that are no longer referenced by published output links.
• Old generated integration-test directories, including their disk images, disposable test DATA overlays and local diagnostic logs. The current results referenced by *-latest links or workstation current-pointer files are kept.
• Old generated package staging copies and service compilation directories.
• This checkout's target/ Rust compilation output. Exported executables in out/ and out/workstation/ remain available. The next Rust build recompiles as needed using the retained Cargo source cache.

The command recognizes the specific temporary-directory names produced by the repository's builders and tests. It never treats all of out/ as disposable. Unknown names are left alone, including ad hoc diagnostic experiments.

What is kept

• Current rootfs archives for every profile, kernel, initramfs, boot, recovery, internal disk and SYSTEM images, through their published symlinks. Links in out/manifests/ and links within retained workspaces also retain their targets.
• Latest published test runs, the current workstation image/emulator fixtures, the current Dasung s6 database, and the newest m9-images.* fixture needed by the media tests. These can still occupy tens of GiB.
• Signed releases such as out/fds-os-0.1.0/, input snapshots such as out/inputs-m12-v5/, and independent restored trees such as out/rebuild-m12-v5-a/. These remain available for release reproduction.
• User-created cartridge images, installed software trees and personal emulator sessions such as out/my-emulator/, including their persistent DATA overlays.
• out/logs/, out/manifests/, packages, downloads, out/cache/, .host/, the Void checkout/build container, and Cargo/Rustup caches outside this checkout.
• Git-tracked files and any recognized workspace containing a .fds-keep entry.

To retain an older generated workspace for investigation, put a marker in it before cleaning:

touch out/m8-vm.YOUR_RUN/.fds-keep
make clean-preview

Replace YOUR_RUN with the actual directory suffix. Remove that marker when the workspace is disposable again. Reserve the generated names for the build/test tools; store personal sessions and images under your own names.

Build-space management

Image builds and VM suites retain workspaces for diagnosis and preserve the last successful published image. Repeat make clean-preview and make clean after completed build batches. Cleanup is explicit; there is no automatic retention limit during a build. Full image builds require tens of GiB per independent tree.

Running safely and rebuilding

Use cleanup sequentially, just like the existing shared-container builds. It holds the existing rootfs/base-package/image-tool locks, excludes another cleanup, and refuses mounted candidate paths or observable active build/VM processes. These checks are safeguards, not permission to start a separate build while cleanup is running. It never follows a candidate symlink into another directory, and refuses a symlinked out/ entirely. Only the checkout containing the script is eligible; there is no arbitrary deletion-path option.

Existing published images and native tools remain usable after cleanup. To refresh exported binaries, run make tooling or make workstation. To rebuild the smoke-test artifacts and rerun build checks:

make smoke-test
make check

After cleanup, run the smoke test before make check, since the checks need its rebuilt executable. Cleanup implementation and validation details are in the developer notes.