vhaudiquet
9e0b6a37a6
pkh put only spoke SFTP to the PPA queue, so a failure of the SSH transport itself (TCP, banner exchange) failed the upload even though dput happily pushes the same files: its plain ppa: profile goes over the anonymous FTP queue of ppa.launchpad.net, the same destination over another port. Classify the SSH connection failures: Transport (the connection never came up: resolution, TCP, banner or key exchange) degrades to that FTP queue — the upload order (payload first, .changes last), the reverse-order DELE cleanup of a failed upload and the per-chunk progress reporting all mirror the SFTP path, sharing cleanup_list. Refused failures (host key not accepted, no matching authentication) stay errors: silently switching transport would bypass the refusal. The FTP client is suppaftp's blocking stream, with the time bounds it does not carry by itself: the control channel's reads and writes, the data channel's writes and connect (through a custom passive stream builder), and the NAT workaround for PASV replies announcing an unroutable address. The queue endpoints (host, port) join data/launchpad.yml next to the SFTP ones, and the FTP transport is covered by unit tests against an in-process fake queue plus a live control-channel handshake with the real server (ignored, network).
155 lines
5.1 KiB
Markdown
155 lines
5.1 KiB
Markdown
# pkh
|
|
|
|
`pkh` is a packaging helper for Debian/Ubuntu packages.
|
|
|
|
## Installation
|
|
|
|
No distribution channel is published yet; build from source:
|
|
|
|
```
|
|
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
|
|
# 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
|
|
```
|
|
|
|
## Roadmap: features needed for 1.0
|
|
|
|
Basically, wrapping the basic debian workflows.
|
|
Missing features:
|
|
- [ ] `pkh pull`
|
|
- [x] Obtain package sources from git
|
|
- [x] Obtain package sources from the archive (fallback)
|
|
- [x] Obtain package source from PPA (--ppa)
|
|
- [x] Obtain a specific version of the package
|
|
- [x] Fetch the correct git branch for series on Ubuntu
|
|
- [ ] Try to fetch the correct git branch for series on Debian, or fallback to the archive
|
|
- [ ] `pkh chlog`
|
|
- [x] Auto-generate changelog entry
|
|
- [x] Extra flags: backport, non-maintainer upload, no change rebuild, ...
|
|
- [x] Select the target series, matching changelog suite names with their series (unstable ≡ sid)
|
|
- [ ] Commit changelog entry
|
|
- [x] `pkh new`
|
|
- [x] Scaffold a new Debian source package (interactive, multiple languages)
|
|
- [ ] `pkh build`
|
|
- [x] Build the source package
|
|
- [ ] `pkh deb`
|
|
- [x] Build the binary package
|
|
- [x] Build for a specific architecture
|
|
- [ ] Three build modes:
|
|
- [x] Build locally (discouraged)
|
|
- [x] Build using unshare chroot, with binary emulation (default)
|
|
- [x] Cross-compilation
|
|
- [ ] Async build
|
|
- [ ] `pkh status`
|
|
- [ ] Show build status
|
|
- [ ] `pkh put`
|
|
- [x] Upload the source package to a PPA (native SFTP, no `dput` dependency)
|
|
- [x] Degrade to the anonymous FTP queue when the SSH connection never comes up (dput's upload method)
|
|
- [ ] Upload the source package to the archive
|
|
- [ ] `pkh commit`
|
|
- [ ] Commit the changes to git
|
|
- [x] `pkh lint`
|
|
- [x] Lint the package
|
|
- [x] `pkh prune`
|
|
- [x] Prune residual pkh build artifacts and caches
|
|
- [ ] `pkh test`
|
|
- [ ] Run autopkgtest
|
|
- [ ] Provide options: local (discouraged), chroot, VM?, ppa
|
|
- [ ] Async test
|
|
|
|
## Nice-to-have features
|
|
|
|
- [ ] 'pkh pull'
|
|
- [ ] Cache the Sources.gz files, to improve speed
|
|
- [ ] Work in an already downloaded package, to git pull and re-fetch orig tar gz
|
|
|