update docs

2026-09-22 13:23:34 +08:00
parent 99bc3d15c5
commit 8a4788fca8
126 changed files with 7198 additions and 2425 deletions
@@ -0,0 +1,90 @@
+# Reclaim build space
+
+Run these from the repository root after stopping builds and test VMs:
+
+```sh
+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:
+
+```sh
+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:
+
+```sh
+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](developer/cleanup.md).