# 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).