update docs
This commit is contained in:
@@ -0,0 +1,131 @@
|
||||
# Reclaim build space
|
||||
|
||||
Development reference and historical context. For current operating instructions, use the [user manual](../README.md). Acceptance applies only to the source and artifacts identified in each record.
|
||||
|
||||
|
||||
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, software bundles 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.
|
||||
|
||||
Cleanup leaves historical acceptance reports intact. Reports mentioning deleted
|
||||
older workspaces are historical records; their files cannot be rechecked until
|
||||
rebuilt, and they never prove that changed source code passed acceptance.
|
||||
|
||||
## Why the directory became so large
|
||||
|
||||
Image builders and integration tests deliberately retain their working
|
||||
directories so failed runs can be inspected and a failed build cannot replace a
|
||||
good published image. Repeated suites therefore accumulate complete rootfs
|
||||
trees, archives and several disk images per case. Before this target existed,
|
||||
this checkout's `out/` measured approximately **900 GiB** of allocated file
|
||||
blocks after repeated M0–M12 and workstation validation runs. That is accumulated
|
||||
history, not the size of a single OS image.
|
||||
|
||||
`make clean` removes superseded workspaces; it does not impose automatic
|
||||
retention during a build. Use the preview periodically. For complete builds,
|
||||
allow tens of GiB per independent tree plus space for VM tests and saved inputs;
|
||||
the small initial smoke test's space requirement does not cover the full suite.
|
||||
|
||||
The preview uses allocated blocks, rather than adding the apparent capacities
|
||||
of sparse VM disks. Hardlinks are counted once within the selection. Reflinks,
|
||||
filesystem snapshots and hardlinks into retained directories can reduce the
|
||||
physical space actually recovered. The command also prints the observed change
|
||||
in filesystem free space; other processes and delayed filesystem accounting can
|
||||
affect that number.
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
`make check` needs the smoke-test binary in `target/`, so run the smoke test first
|
||||
after cleaning. `make clean-test` independently exercises cleanup selection,
|
||||
preserved releases/data, repeated runs, symlinks, tracked files, read-only guest
|
||||
directories, hardlinks, locks, live processes and mount rejection using tiny
|
||||
temporary repositories. It does not build OS images or boot VMs.
|
||||
|
||||
## Recorded cleanup validation
|
||||
|
||||
On the development checkout, cleanup removed 576 disposable directories with
|
||||
a 638.00 GiB allocated footprint. The filesystem reported 605.86 GiB more free
|
||||
space immediately afterward; `out/` dropped from about 900 GiB to 268 GiB.
|
||||
The retained space includes independent release rebuilds, input snapshots and
|
||||
current image/test workspaces. A second preview selected zero directories.
|
||||
|
||||
All 52 recorded current image/tool and frozen release file hashes remained
|
||||
identical, and all 33 published links remained intact. `make bootstrap`,
|
||||
`make smoke-test`, `make check` and all nine cleanup fixture tests passed.
|
||||
The smoke test skipped its optional ARM execution because host `qemu-aarch64`
|
||||
was unavailable; its ELF checks passed. This validates host cleanup and does
|
||||
not add any physical Pi or monitor acceptance evidence. The local command log
|
||||
is `out/logs/cleanup.log`, with a summary in
|
||||
`out/manifests/cleanup-acceptance.json`.
|
||||
Reference in New Issue
Block a user