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:
@@ -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
|
||||||
|
|||||||
Reference in New Issue
Block a user