pkh

pkh is a packaging helper for Debian/Ubuntu packages.

Installation

From crates.io:

cargo install pkh

Or build from source (the same system packages are needed either way):

sudo apt install pkg-config libssl-dev libgpg-error-dev libgpgme-dev
git clone https://git.vhaudiquet.fr/vhaudiquet/pkh.git
cd pkh
cargo install --path .

At runtime pkh shells out to the Debian packaging toolchain (git, dpkg-dev, quilt, mmdebstrap, lintian, pristine-tar, ...): 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 (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.

Thus, pkh uses similar options for all subcommands (with very few command-specific options):

Options:
  -s, --series <series>    Target package distribution series
  -d, --dist <dist>        Target package distribution (debian, ubuntu)
  -v, --version <version>  Target package version
  -a, --arch <arch>        Target architecture (amd64, arm64, riscv64, ...)
  -p, --pocket <pocket>    Target distribution pocket (updates, security, proposed, ...)
      --ppa <ppa>          Do the action in/for a specific PPA

Commands and workflows include:

Commands:
  new    Scaffold a new Debian source package (buildable right away)
  pull   Pull a source package from the archive or git
  chlog  Auto-generate changelog entry, editing it, committing it afterwards
  build  Build the source package (into a .dsc)
  put    Upload the built source package to a PPA
  deb    Build the source package into binary package (.deb)
  lint   Lint the package (lintian wrapper + pkh-native checks)
  prune  Prune residual pkh build artifacts and caches
  help   Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

Examples

A typical workflow to patch an Ubuntu package hello on the development release could be:

# Obtain the package source
git ubuntu clone hello
cd hello
# Apply the patch to the package
...
dpkg-source --commit
# Increment version number
dch
# Test that the patch builds
git ubuntu export-orig
dpkg-buildpackage -S -I -i -nc -d
sbuild --dist resolute --arch amd64 ../hello_xxx.dsc
# Upload the package to a ppa
dput ppa:user/hello_xxx ../hello_xxx_source.changes
# Commit the changes to git
git add debian/patches/xxx.patch
git commit -m "Applied patch xxx"
git add debian/changelog
git commit -m "changelog"
git checkout -b xxx
git push xxx user-fork

That is a lot of different tools and operations. With pkh, the same workflow:

# Obtain the package source (and orig tarball)
pkh pull hello # needs -d ubuntu if you are not running Ubuntu
# Apply the patch to the package
...
git add debian/patches/xxx.patch
git commit -m "Applied patch xxx"
pkh chlog
git add debian/changelog
git commit -m "d/changelog"
# Test that the package builds
pkh build
pkh deb
# Upload the package to a ppa
pkh put --ppa user/hello_xxx
# Push the commits to your fork
git push xxx user-fork

Incremental builds (build sessions)

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:

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 --keep          # keep the session even after a successful build
                        # (iterate: edit, `pkh deb --resume --keep`, ...)
pkh prune               # garbage-collect old sessions (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.

Future improvement ideas

• pull: try to fetch the correct git branch for series on Debian
• deb: asynchronous build, detachable and monitorable
• put: allow uploads to Debian or Ubuntu archives
• test: add 'pkh test' to run autopkgtests
• pull: cache Sources.gz files to improve speed
• pull: 'pkh pull' in a package tree should git pull and re-fetch orig tgz