132 lines
6.7 KiB
Markdown
132 lines
6.7 KiB
Markdown
# 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`.
|