From b246b30eac6d7278bc3029a626c480afff879b85 Mon Sep 17 00:00:00 2001 From: Valentin Haudiquet Date: Fri, 2 Oct 2026 21:28:21 +0200 Subject: [PATCH] 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. --- README.md | 47 ++++++++++++++++++++++++----------------------- 1 file changed, 24 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index fdf9ae3..ed00239 100644 --- a/README.md +++ b/README.md @@ -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 Target package distribution series @@ -126,13 +127,13 @@ Every `pkh deb` build records its metadata under `/var/tmp/pkh/sessions///`: 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/-/`, 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//`, 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 ` 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 ` 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