1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
name: Release
# Publishing is driven by a tag, because the tag is the only thing that makes a
# release reproducible: the binaries, the notes and the image all come from one
# commit, and re-running the workflow cannot quietly produce something else.
#
# `workflow_dispatch` builds everything and publishes nothing. The expensive
# part of a release is the four platform builds, and finding out they are broken
# should not require burning a version number to do it.
on:
push:
tags:
- "v*"
workflow_dispatch:
permissions:
contents: read
env:
CARGO_TERM_COLOR: always
CARGO_INCREMENTAL: 0
jobs:
# A tag is the one input to a release that nobody reviews, and the failure it
# causes is expensive: `v0.7.1` on a tree that still says `0.7.0` publishes
# binaries reporting the wrong version, and a tag cannot be moved once anyone
# has fetched it. This is the cheap check that makes that impossible.
verify:
name: verify version
runs-on: ubuntu-latest
outputs:
version: ${{ steps.version.outputs.version }}
steps:
- uses: actions/checkout@v4
- id: version
shell: bash
run: |
set -euo pipefail
crate="$(grep -m1 '^version = ' Cargo.toml | cut -d'"' -f2)"
echo "Cargo.toml version: $crate"
echo "version=$crate" >> "$GITHUB_OUTPUT"
if [ "$GITHUB_REF_TYPE" = "tag" ]; then
tag="${GITHUB_REF_NAME#v}"
if [ "$tag" != "$crate" ]; then
echo "::error::tag ${GITHUB_REF_NAME} does not match Cargo.toml version ${crate}"
exit 1
fi
fi
# An unreleased version with no changelog section means the notes
# below would be empty, which is worth failing over before four
# platform builds rather than after them.
if ! grep -q "^## \[${crate}\]" CHANGELOG.md; then
echo "::error::CHANGELOG.md has no '## [${crate}]' section"
exit 1
fi
# The four artifacts, and why these four:
#
# linux-x86_64 the full binary -- headless, terminal UI and GUI
# linux-x86_64-headless the same core with no front-end, for CI images
# windows-x86_64 full binary; the audience least likely to compile
# macos-arm64 full binary, Apple Silicon
#
# The `gui` builds are strict supersets: one binary serves `-c`, the terminal
# UI and `--gui`, so a user who wants the GUI and a user who wants the CLI
# download the same file. The GUI does not force a display dependency on the
# others either -- winit `dlopen`s X11/Wayland, so the binary still starts on
# a machine that has neither and only needs them for `--gui` itself.
#
# Linux builds on the *oldest* runner available rather than `ubuntu-latest`.
# glibc is backward but not forward compatible, so a binary built against
# 24.04's glibc 2.39 refuses to start on anything older, while 22.04's 2.35
# covers Ubuntu 22.04+, Debian 12+ and Fedora 36+. It does *not* reach RHEL 9,
# which is on 2.34. Slim containers are out of reach for a different reason --
# they carry no libxml2 -- and that is what the image is for.
build:
needs: verify
name: ${{ matrix.name }}
runs-on: ${{ matrix.os }}
strategy:
fail-fast: false
matrix:
include:
- name: linux-x86_64
os: ubuntu-22.04
features: --features gui
- name: linux-x86_64-headless
os: ubuntu-22.04
features: --no-default-features
- name: windows-x86_64
os: windows-latest
features: --features gui
- name: macos-arm64
os: macos-latest
features: --features gui
steps:
- uses: actions/checkout@v4
- uses: dtolnay/rust-toolchain@stable
- uses: Swatinem/rust-cache@v2
with:
key: release-${{ matrix.name }}
# Named explicitly rather than relied on from the runner image: a release
# build should not change because a base image dropped a package.
- name: Install Linux build dependencies
if: runner.os == 'Linux'
run: |
sudo apt-get update
sudo apt-get install -y --no-install-recommends \
pkg-config libxml2-dev libclang-dev perl make
# Only the GUI shape needs the display headers; the headless artifact is
# built on the same runner and must not acquire them by accident.
- name: Install Linux GUI build dependencies
if: runner.os == 'Linux' && contains(matrix.features, 'gui')
run: |
sudo apt-get install -y --no-install-recommends \
libxkbcommon-dev libwayland-dev libx11-dev libxcursor-dev \
libxrandr-dev libxi-dev libgl1-mesa-dev
# See the `platform` job in ci.yml: vcpkg is how `libxml` finds libxml2 on
# MSVC, `VCPKG_ROOT` is how vcpkg-rs finds vcpkg, and NASM is the one
# prerequisite the Windows image does not ship.
- name: Install libxml2 and NASM (Windows)
if: runner.os == 'Windows'
run: |
& "$env:VCPKG_INSTALLATION_ROOT\vcpkg" install libxml2:x64-windows-static-md
echo "VCPKG_ROOT=$env:VCPKG_INSTALLATION_ROOT" >> $env:GITHUB_ENV
echo "LIBCLANG_PATH=C:\Program Files\LLVM\bin" >> $env:GITHUB_ENV
choco install nasm -y --no-progress
echo "C:\Program Files\NASM" >> $env:GITHUB_PATH
# hurl 8.0.1's build script embeds a Windows icon from
# `../../bin/windows/logo.ico`, a path relative to hurl's own git
# checkout. The crates.io package ships nothing outside its own
# directory, so on Windows `rc.exe` fails with RC2135 and the build
# script panics -- hurl as a library simply cannot be built on Windows
# from crates.io. Upstream fixed it by guarding the path
# (Orange-OpenSource/hurl#5207, merged 2026-09-14) but has not released
# it; 8.0.1 is still the newest crate.
#
# rc.exe resolves that relative path from the build script's working
# directory, which Cargo sets to the package root -- so `../../` lands in
# `registry/src`, and putting a file there is enough to satisfy it. We
# supply *our own* icon rather than fetching hurl's: the resource is
# linked into the final executable, so hurl's logo would otherwise become
# paperboy.exe's icon. Remove this once hurl 8.1.0 is out.
- name: Work around hurl's unreachable Windows icon (hurl#5207)
if: runner.os == 'Windows'
run: |
$cargoHome = if ($env:CARGO_HOME) { $env:CARGO_HOME } else { Join-Path $env:USERPROFILE ".cargo" }
$dir = Join-Path $cargoHome "registry\src\bin\windows"
New-Item -ItemType Directory -Force -Path $dir | Out-Null
Copy-Item "assets\windows\paperboy.ico" (Join-Path $dir "logo.ico") -Force
# macOS bundles libxml2 in the dyld shared cache on every install, and the
# SDK ships its headers and a linker stub -- but no pkg-config file, so
# `libxml`'s pkg-config probe cannot find the one copy that is guaranteed
# to be present. Synthesising the `.pc` is what makes that copy usable:
# the binary then links `/usr/lib/libxml2.2.dylib`, a path every Mac has,
# and the archive needs nothing installed. `xcrun` keeps this correct as
# the SDK moves between Xcode releases.
#
# The previous approach -- Homebrew's keg-only libxml2 plus
# `LIBXML2_STATIC` -- was a no-op, and silently so. Homebrew's bottle
# ships no `libxml2.a` at all, and pkg-config-rs only emits `static=`
# when it can see one in the `-L` directory; finding none it falls back
# to an ordinary dynamic link without warning. The build then succeeds
# having baked in an `/opt/homebrew` path that exists on this runner and
# on no user's Mac, which is exactly what 0.7.0's first attempt shipped.
# Supplying an `.a` would not have rescued it either: Apple's linker has
# no `-Bstatic`, so `-lxml2` against a directory holding both files picks
# the dylib regardless, and forcing the archive means linking it by
# absolute path.
- name: Point pkg-config at the macOS SDK's libxml2
if: runner.os == 'macOS'
run: |
set -euo pipefail
# `pkg-config` is a build tool here, not a link dependency: installing
# it from Homebrew has no bearing on what the binary ends up linking.
command -v pkg-config >/dev/null || brew install pkg-config
sdk="$(xcrun --show-sdk-path)"
header="$sdk/usr/include/libxml2/libxml/xmlversion.h"
version="$(awk -F'"' '/define LIBXML_DOTTED_VERSION/ {print $2}' "$header")"
if [ -z "$version" ]; then
echo "::error::no LIBXML_DOTTED_VERSION in $header"
exit 1
fi
echo "using the SDK's libxml2 $version from $sdk"
mkdir -p "$RUNNER_TEMP/pkgconfig"
cat > "$RUNNER_TEMP/pkgconfig/libxml-2.0.pc" <<PC
Name: libxml2
Description: libxml2 from the macOS SDK
Version: $version
Libs: -lxml2
Cflags: -I$sdk/usr/include/libxml2
PC
echo "PKG_CONFIG_PATH=$RUNNER_TEMP/pkgconfig" >> "$GITHUB_ENV"
# `--locked` for the same reason the README recommends it to users: a
# release must be the dependency set that was tested, not whatever
# resolved newest on the morning it was cut.
- name: Build
run: cargo build --release --locked ${{ matrix.features }}
# Which libxml2 got linked is the difference between an artifact that runs
# on any Mac and one that runs only on a machine with the same Homebrew
# prefix -- and nothing about a successful build says which happened.
# This is the step that has to fail, rather than a user discovering it.
#
# Both halves matter: the first catches a Homebrew path reappearing, and
# the second catches libxml2 vanishing from the link entirely (a stray
# `LIBXML2_STATIC`, say), which would otherwise look like a pass.
- name: Check the macOS binary is self-contained
if: runner.os == 'macOS'
run: |
set -euo pipefail
otool -L target/release/paperboy
if otool -L target/release/paperboy | grep -E '/opt/homebrew|/Cellar/'; then
echo "::error::binary links a Homebrew dylib and will not run on a clean Mac"
exit 1
fi
if ! otool -L target/release/paperboy | grep -q '/usr/lib/libxml2'; then
echo "::error::binary does not link the system libxml2 at /usr/lib"
exit 1
fi
- name: Package (unix)
if: runner.os != 'Windows'
shell: bash
run: |
set -euo pipefail
dir="paperboy-${{ needs.verify.outputs.version }}-${{ matrix.name }}"
mkdir "$dir"
cp target/release/paperboy "$dir/"
cp README.md CHANGELOG.md LICENSE "$dir/"
tar -czf "$dir.tar.gz" "$dir"
ls -l "$dir.tar.gz"
- name: Package (windows)
if: runner.os == 'Windows'
run: |
$dir = "paperboy-${{ needs.verify.outputs.version }}-${{ matrix.name }}"
New-Item -ItemType Directory -Path $dir | Out-Null
Copy-Item target\release\paperboy.exe $dir\
Copy-Item README.md, CHANGELOG.md, LICENSE $dir\
Compress-Archive -Path $dir -DestinationPath "$dir.zip"
Get-Item "$dir.zip"
- uses: actions/upload-artifact@v4
with:
name: ${{ matrix.name }}
path: |
paperboy-*.tar.gz
paperboy-*.zip
if-no-files-found: error
# Only a tag publishes. A `workflow_dispatch` run stops after `build`, which
# is the point of being able to trigger one.
# Ordered after `docker` deliberately. The release notes document
# `ghcr.io/jhobern/paperboy`, so publishing them while the image push has
# failed advertises something that isn't there -- and a release, unlike a job,
# cannot be quietly re-run. Failing before the announcement is recoverable;
# failing after it is not.
release:
needs:
if: github.ref_type == 'tag'
name: publish release
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- uses: actions/checkout@v4
- uses: actions/download-artifact@v4
with:
path: dist
merge-multiple: true
# Checksums are what lets someone verify a download they did not build,
# which is the whole reason to publish binaries rather than say "cargo
# install". Generated next to the files so the paths in it are the names
# the release actually serves.
- name: Checksums
working-directory: dist
run: |
sha256sum * > SHA256SUMS
cat SHA256SUMS
# The release notes are the changelog section for this version, rather
# than a hand-written summary that can disagree with it.
- name: Release notes
run: |
awk -v v="${{ needs.verify.outputs.version }}" '
$0 ~ "^## \\[" v "\\]" { found = 1; next }
found && /^## \[/ { exit }
found { print }
' CHANGELOG.md > notes.md
echo "--- notes.md ---"
cat notes.md
# A SemVer prerelease (`0.8.0-beta.1`) must not be offered as the current
# version: GitHub's "Latest release" badge, and every tool that reads it,
# follows this flag rather than the tag's name.
- name: Publish
env:
GH_TOKEN: ${{ github.token }}
run: |
set -euo pipefail
version="${{ needs.verify.outputs.version }}"
case "$version" in
*-*) prerelease=--prerelease ;;
*) prerelease= ;;
esac
gh release create "$GITHUB_REF_NAME" \
--title "PaperBoy $version" \
--notes-file notes.md \
--verify-tag \
${prerelease} \
dist/*
# The container is the answer for the audience the glibc binaries do not
# reach: slim images and Alpine-based CI, where there is no system libxml2.
# A static musl binary would also solve it, but `bindgen` cannot `dlopen`
# libclang on a musl host and `libxml`'s `static` feature cannot be enabled
# from here (hurl pulls it in with `runtime`, and Cargo feature unification
# only ever adds features) -- so it would take a patched hurl, and the
# resulting binary still could not run the GUI.
# Unlike the jobs above this one runs for a `workflow_dispatch` too -- it
# builds either way and only pushes for a tag. A dry run that skipped it
# would leave the Dockerfile as the one part of a release never exercised
# before the release itself.
docker:
needs:
name: publish image
runs-on: ubuntu-latest
permissions:
contents: read
packages: write
steps:
- uses: actions/checkout@v4
- name: Build
run: |
set -euo pipefail
image="ghcr.io/${GITHUB_REPOSITORY,,}"
version="${{ needs.verify.outputs.version }}"
docker build -t "$image:$version" .
# Worth the half-second: an image that builds but cannot run its own
# entrypoint is a failure mode the build alone does not catch, and the
# release job publishes notes that tell people to run exactly this.
- name: Smoke test
run: |
set -euo pipefail
image="ghcr.io/${GITHUB_REPOSITORY,,}"
docker run --rm "$image:${{ needs.verify.outputs.version }}" --version
- name: Log in to ghcr.io
if: github.ref_type == 'tag'
run: echo "${{ github.token }}" | docker login ghcr.io -u "${{ github.actor }}" --password-stdin
- name: Push
if: github.ref_type == 'tag'
run: |
set -euo pipefail
image="ghcr.io/${GITHUB_REPOSITORY,,}"
version="${{ needs.verify.outputs.version }}"
docker push "$image:$version"
# `latest` is what an unqualified `docker run` resolves to, so a
# prerelease must not take it.
case "$version" in
*-*) echo "prerelease $version: leaving :latest alone" ;;
*)
docker tag "$image:$version" "$image:latest"
docker push "$image:latest"
;;
esac