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, At runtime pkh shells out to the Debian packaging toolchain (git,
dpkg-dev, quilt, mmdebstrap, lintian, pristine-tar, autopkgtest, ...): dpkg-dev, quilt, mmdebstrap, lintian, pristine-tar, autopkgtest, ...).
install the ones your workflows use, or build the classic snap from Install the ones your workflows use, or build the classic snap from
`snap/snapcraft.yaml` (`snapcraft pack`), which carries them. `snap/snapcraft.yaml` (`snapcraft pack`), which carries them.
## Usage and features ## Usage and features
### Basic concepts ### 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`, (`git`, `git-ubuntu`, `pull-debian-sources`, `pull-lp-sources`, `pull-ppa-sources`,
`dch`, `dpkg-buildpackage`, `sbuild`, `dpkg-source`, `quilt`, ...) into one tool, that `dch`, `dpkg-buildpackage`, `sbuild`, `dpkg-source`, `quilt`, ...) into
would have the same interface for everything, while being smarter at integrating all workflows. 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: Options:
-s, --series <series> Target package distribution series -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 `/var/tmp/pkh/sessions/<target>/<id>/`: the manifest (identity, fork
lineage, outcome, the sha of the chroot tarball it used) and a full 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 `log/build.log` tee of the build output. The chroot itself is per-run
scratch — extracted fresh from the sha-verified mmdebstrap tarball cache scratch, extracted fresh from the sha-verified mmdebstrap tarball cache
on every run and removed at the end, plain and `--incremental` alike — on every run and removed at the end, plain and `--incremental` alike,
so records stay small. What `--incremental` buys is the record's so records stay small. `--incremental` keeps the record's staged tree
**staged tree** (`tree-upper/`): the overlay upperdir where the build's (`tree-upper/`), the overlay upperdir where the build's writes land,
writes land, holding the compiled objects. 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 `/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 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 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 drops the debs the archive no longer serves). `pkh prune` removes the
caches untouched for a week. 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 gets a shared ccache (at `/var/tmp/pkh/ccache/<target>/`, mounted at
`/var/cache/pkh-ccache`) wired in through a compiler PATH shim — `/var/cache/pkh-ccache`) wired in through a compiler PATH shim that
`gcc`, `g++`, `cc` and `c++` resolve to ccache — with content-keyed resolves `gcc`, `g++`, `cc` and `c++` to ccache, with content-keyed
cache checks (`CCACHE_COMPILERCHECK=content`), so cache hits survive cache checks (`CCACHE_COMPILERCHECK=content`), so cache hits survive
the fresh toolchain of a new chroot. The cache is capped at 10G per the fresh toolchain of a new chroot. The cache is capped at 10G per
target (override with `PKH_CCACHE_MAXSIZE`); `pkh deb --no-ccache` target (override with `PKH_CCACHE_MAXSIZE`); `pkh deb --no-ccache`
bypasses the shim and cache entirely, an escape hatch for rules that bypasses the shim and cache entirely, an escape hatch for rules that
mishandle compiler wrappers (kbuild-style flavour configs). mishandle compiler wrappers (kbuild-style flavour configs).
`--incremental` forks a previous record — a copy, the base is never `--incremental` forks a copy of a previous record and never modifies
modified — so a failed run can never destroy the last-good state it was 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 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 tarball sha still matches the cache (the toolchain did not move) and the
changelog version is unchanged; otherwise the fork builds from a fresh 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 Packages whose `debian/rules` keeps an input-untracked stamp cache (the
kernels' `debian/stamps`) declare it in the quirks data kernels' `debian/stamps`) declare it in the quirks data
(`resume_clear`): forked builds drop the cache so the wrapper steps — (`resume_clear`). Forked builds drop the cache, so the wrapper steps,
including the kernel's flavour config export — re-run over the including the kernel's flavour config export, re-run over the
incremental inner builds, and a config edit is never silently ignored. 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 A build killed hard (OOM) can leave its chroot behind; the next run of
that target sweeps it (unmounting and escalating through sudo when that target sweeps it (unmounting and escalating through sudo when
needed), and `pkh prune` collects the rest. needed), and `pkh prune` collects the rest.
On a pinned runner — a machine that must resolve every package from one On a pinned runner, a machine that must resolve every package from one
mirror, typically a caching proxy — `pkh deb --mirror <url>` builds the mirror (typically a caching proxy), `pkh deb --mirror <url>` builds the
chroot and resolves every package from that base URL: the mirror is chroot and resolves every package from that base URL. The mirror is
passed to mmdebstrap at bootstrap, so the chroot tarball's apt sources 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 carry it and every apt inside the build follows. The mirror must serve
every suite and architecture the build resolves (the security pocket every suite and architecture the build resolves (the security pocket