docs: tighten the README prose

Plain-speech pass: drop the em-dash asides and mid-sentence colons,
reword the boldface digest constructions ("What --incremental buys
is ..."), and replace the fluffy intro ("aims at wrapping ... while
being smarter at integrating all workflows") with what pkh actually
does. No content changes.
This commit is contained in:
2026-10-02 21:28:21 +02:00
parent e4612ca128
commit b246b30eac
+24 -23
View File
@@ -22,20 +22,21 @@ cargo install --path .
```
At runtime pkh shells out to the Debian packaging toolchain (git,
dpkg-dev, quilt, mmdebstrap, lintian, pristine-tar, autopkgtest, ...):
install the ones your workflows use, or build the classic snap from
dpkg-dev, quilt, mmdebstrap, lintian, pristine-tar, autopkgtest, ...).
Install the ones your workflows use, or build the classic snap from
`snap/snapcraft.yaml` (`snapcraft pack`), which carries them.
## Usage and features
### Basic concepts
`pkh` aims at wrapping the different debian tools and workflows
`pkh` wraps the different Debian tools and workflows
(`git`, `git-ubuntu`, `pull-debian-sources`, `pull-lp-sources`, `pull-ppa-sources`,
`dch`, `dpkg-buildpackage`, `sbuild`, `dpkg-source`, `quilt`, ...) into one tool, that
would have the same interface for everything, while being smarter at integrating all workflows.
`dch`, `dpkg-buildpackage`, `sbuild`, `dpkg-source`, `quilt`, ...) into
one tool with the same interface for everything, which also handles each
workflow's specifics.
Thus, `pkh` uses similar options for all subcommands (with very few command-specific options):
The same options work across subcommands (with very few command-specific options):
```
Options:
-s, --series <series> Target package distribution series
@@ -126,13 +127,13 @@ Every `pkh deb` build records its metadata under
`/var/tmp/pkh/sessions/<target>/<id>/`: the manifest (identity, fork
lineage, outcome, the sha of the chroot tarball it used) and a full
`log/build.log` tee of the build output. The chroot itself is per-run
scratch — extracted fresh from the sha-verified mmdebstrap tarball cache
on every run and removed at the end, plain and `--incremental` alike —
so records stay small. What `--incremental` buys is the record's
**staged tree** (`tree-upper/`): the overlay upperdir where the build's
writes land, holding the compiled objects.
scratch, extracted fresh from the sha-verified mmdebstrap tarball cache
on every run and removed at the end, plain and `--incremental` alike,
so records stay small. `--incremental` keeps the record's staged tree
(`tree-upper/`), the overlay upperdir where the build's writes land,
holding the compiled objects.
Fresh chroots do not mean fresh downloads: every chroot's
Fresh chroots share their downloads. Every chroot's
`/var/cache/apt/archives` is a bind mount over a shared apt download
cache at `/var/tmp/pkh/apt-cache/<series>-<arch>/`, which the installs
of one run fill and the next runs reuse (apt is configured to keep the
@@ -140,18 +141,18 @@ downloaded packages, and an `apt-get autoclean` at the end of each run
drops the debs the archive no longer serves). `pkh prune` removes the
caches untouched for a week.
Fresh chroots do not mean fresh compiles either: every run's chroot
Fresh chroots share their compiles too. Every run's chroot
gets a shared ccache (at `/var/tmp/pkh/ccache/<target>/`, mounted at
`/var/cache/pkh-ccache`) wired in through a compiler PATH shim —
`gcc`, `g++`, `cc` and `c++` resolve to ccache — with content-keyed
`/var/cache/pkh-ccache`) wired in through a compiler PATH shim that
resolves `gcc`, `g++`, `cc` and `c++` to ccache, with content-keyed
cache checks (`CCACHE_COMPILERCHECK=content`), so cache hits survive
the fresh toolchain of a new chroot. The cache is capped at 10G per
target (override with `PKH_CCACHE_MAXSIZE`); `pkh deb --no-ccache`
bypasses the shim and cache entirely, an escape hatch for rules that
mishandle compiler wrappers (kbuild-style flavour configs).
`--incremental` forks a previous record — a copy, the base is never
modified — so a failed run can never destroy the last-good state it was
`--incremental` forks a copy of a previous record and never modifies
the base, so a failed run cannot destroy the last-good state it was
built from. The staged tree is carried only when the base's recorded
tarball sha still matches the cache (the toolchain did not move) and the
changelog version is unchanged; otherwise the fork builds from a fresh
@@ -190,16 +191,16 @@ series/architecture.
Packages whose `debian/rules` keeps an input-untracked stamp cache (the
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.
(`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.
A build killed hard (OOM) can leave its chroot behind; the next run of
that target sweeps it (unmounting and escalating through sudo when
needed), and `pkh prune` collects the rest.
On a pinned runner — a machine that must resolve every package from one
mirror, typically a caching proxy — `pkh deb --mirror <url>` builds the
chroot and resolves every package from that base URL: the mirror is
On a pinned runner, a machine that must resolve every package from one
mirror (typically a caching proxy), `pkh deb --mirror <url>` builds the
chroot and resolves every package from that base URL. The mirror is
passed to mmdebstrap at bootstrap, so the chroot tarball's apt sources
carry it and every apt inside the build follows. The mirror must serve
every suite and architecture the build resolves (the security pocket