deb: rework build sessions into immutable per-build records
The single mutable session per identity loses the last-good state: a failed run after a good one adopts the session in place and leaves only the failed state behind, so "continue from the last success" was impossible. Each build now records an immutable record under /var/tmp/pkh/sessions/<slug>/<id>/ (chroot, tree-upper, journal, manifest), and --incremental forks a NEW record — a full copy of the base's chroot and, at the same changelog version, its staged artifacts — under the base's flock, never mutating the base itself. Selection picks the newest successful record of the identity among the last five usable, falling back to the newest when none succeeded, and --incremental <id> pins an exact record (failed ones allowed: their environment may be fine). The lifecycle is strict keep-iff-incremental: plain runs build in a throwaway record discarded on success, failure and interrupt alike (the SIGINT cleanup hook follows the same policy), while --incremental records are always kept. Each identity keeps its newest five records; pkh prune's 7-day sweep and orphaned-lock cleanup follow the nested layout. --resume and --keep are removed (no aliases): their adoption-in-place and keep-on-success semantics are exactly what the record model replaces. pkh deb list shows id, outcome, tree version, fork lineage and age. README rewritten around the record workflow.
This commit is contained in:
@@ -120,43 +120,45 @@ Without a version tag, that search is capped at the last 500 commits
|
||||
(`--limit <n>`, `0` = unlimited): beyond the cap, the entry simply starts
|
||||
at the oldest commit searched, which keeps the run fast on large histories.
|
||||
|
||||
### Incremental builds (build sessions)
|
||||
### Incremental builds (build records)
|
||||
|
||||
Every `pkh deb` build records a **session** under `/var/tmp/pkh/sessions`:
|
||||
the bootstrapped chroot, the installed build dependencies and the build
|
||||
artifacts of the staged tree. When a build fails (or is interrupted), the
|
||||
session is kept and can be resumed:
|
||||
Every `pkh deb` build runs in its own immutable **record** under
|
||||
`/var/tmp/pkh/sessions/<target>/<id>/`: the bootstrapped chroot, the
|
||||
installed build dependencies and the build artifacts of the staged
|
||||
tree. `--incremental` forks a previous record — a full copy, the base
|
||||
is never modified — so a failed run can never destroy the last-good
|
||||
environment it was built from:
|
||||
|
||||
```
|
||||
pkh deb # fails after 25 minutes
|
||||
pkh deb --resume # reuses the chroot, build deps and objects;
|
||||
# only what changed is recompiled
|
||||
pkh deb list # the sessions of this tree, with their ids
|
||||
pkh deb --resume <id> # resume a specific session
|
||||
pkh deb --incremental # one-flag iterate loop: adopts the newest
|
||||
# session like `--resume` and keeps it on
|
||||
# success (with `--resume <id>`, only adds keep)
|
||||
pkh deb --keep # keep the session even after a successful build
|
||||
# (iterate: edit, `pkh deb --resume --keep`, ...)
|
||||
pkh prune # garbage-collect old sessions (7-day retention)
|
||||
pkh deb # fully ephemeral: nothing is kept, even on
|
||||
# failure or interrupt
|
||||
pkh deb --incremental # fork the newest successful record of the
|
||||
# target (last five usable): the chroot, build
|
||||
# deps and, at the same version, the objects
|
||||
# are reused; only what changed is recompiled.
|
||||
# The result is always kept (success or
|
||||
# failure) for the next fork
|
||||
pkh deb --incremental <id>
|
||||
# fork that exact record (see `pkh deb list`);
|
||||
# a failed record is fine if its environment is
|
||||
pkh deb list # the records of this tree: id, outcome,
|
||||
# version, fork lineage, age
|
||||
pkh prune # garbage-collect records (7-day retention)
|
||||
```
|
||||
|
||||
A plain `pkh deb` never reuses a session — everything is rechecked from
|
||||
scratch — and it replaces the session of its target. `pkh deb --resume`
|
||||
refuses to adopt a session built for a different series/architecture.
|
||||
|
||||
`pkh deb --incremental` combines `--resume` (without an ID) with
|
||||
`--keep`, so iterating is a single flag: each successful build keeps the
|
||||
session and the next `--incremental` build reuses it, recompiling only
|
||||
what changed. With an explicit `--resume <id>` it only adds keep. A plain
|
||||
`pkh deb` still never reuses a session and consumes it on success.
|
||||
Each target (series/arch) keeps its last five records — older ones are
|
||||
pruned as new ones are created, and `pkh prune` removes those untouched
|
||||
for a week. `pkh deb --incremental` never forks a record built for a
|
||||
different series/architecture, and a plain `pkh deb` still never
|
||||
reuses anything: it builds in a throwaway record that is discarded on
|
||||
success, failure and interrupt alike.
|
||||
|
||||
Packages whose `debian/rules` keeps an input-untracked stamp cache (the
|
||||
kernels' `debian/stamps`) declare it in the quirks data (`resume_clear`):
|
||||
resumed builds drop the cache so the wrapper steps — including the
|
||||
kernel's flavour config export — re-run over the incremental inner
|
||||
builds, and a config edit is never silently ignored. If a build died
|
||||
hard (OOM kill), the next build unmounts and clears the leftover session
|
||||
kernels' `debian/stamps`) declare it in the quirks data
|
||||
(`resume_clear`): forked builds drop the cache so the wrapper steps —
|
||||
including the kernel's flavour config export — re-run over the
|
||||
incremental inner builds, and a config edit is never silently ignored.
|
||||
If a build died hard (OOM kill), the next fork unmounts the leftover
|
||||
state first (escalating through sudo when needed).
|
||||
|
||||
### Running the DEP-8 tests
|
||||
|
||||
Reference in New Issue
Block a user