beffroi-tools/docs/releases.md

106 lines
5.2 KiB
Markdown

# Cross builds and portable releases
Run commands from the repository root. The primary release workflow is the
`rust_realease` named bundle described below. The standalone packager remains
available for manual/offline packaging until native acceptance tests are complete. Cross needs Docker or Podman;
`Cross.toml` selects Windows GNU x64 and Linux GNU x64 images. Jenkins does not
run release builds or publish releases.
```sh
cross build --locked -p pptx-reporter --release --target x86_64-pc-windows-gnu
cross build --locked -p pptx-reporter --release --target x86_64-unknown-linux-gnu
python3 scripts/package-portable.py --target x86_64-pc-windows-gnu --fetch-ffprobe
python3 scripts/package-portable.py --target x86_64-unknown-linux-gnu --fetch-ffprobe
```
The packager reads `target/<target>/release/` and produces a Windows ZIP or Linux
`.tar.gz` in `dist/`, plus a SHA-256 checksum. Each includes GUI and CLI binaries,
FFprobe, licenses/provenance and quick-start instructions. Existing archives
are protected; use `--output DIR` for a new test build.
## FFprobe
`scripts/fetch_ffprobe.py` downloads BtbN FFmpeg 9.0 release-branch, non-shared
LGPL builds. It verifies GitHub's archive SHA-256, executable format and x86-64
architecture, then tests `ffprobe -version` on a matching host. Foreign binaries
are inspected without execution. Verified binaries/notices are cached in
ignored `downloads/ffprobe/`; no FFprobe binary is committed.
The default upstream `latest` tag moves. Pin repeatable builds with
`--ffprobe-release TAG --ffprobe-sha256 HASH`. Provenance records release/asset
IDs, download URL and digest. Cached files are checked on reuse, but online
metadata verification still requires GitHub access.
For offline packaging or another provider:
```sh
python3 scripts/package-portable.py --target x86_64-pc-windows-gnu \
--ffprobe /path/to/ffprobe.exe --ffprobe-licenses /path/to/notices
```
Review upstream platform requirements and distribution notices for the selected
build. Test Windows launch, drag/drop, file dialogs, scaling, Unicode paths and
opening reports on a Windows machine; cross-compilation alone cannot verify them.
## Release automation
Root `Cargo.toml` → `workspace.package.version` is authoritative. The reporter
inherits it; its manifest contains cargo-binstall metadata. `rust-release.toml`
configures targets and the canonical Gitea URL for
[`rust_realease`](https://proxy.dandaedre.com/gitea/idle-org/rust_realease):
```sh
rust_realease . --package pptx-reporter --dry-run
rust_realease . --package pptx-reporter --compile-only
```
Publication needs a clean checkout and a matching explicitly created/pushed
version tag. The existing local `v0.1.0` marks the original trial, not subsequent
changes; do not move it implicitly.
The `portable` named bundle adds a Windows ZIP and Linux `.tgz`, containing both
Cargo binaries, adjacent FFprobe, quick-start instructions and licenses. Canonical
cargo-binstall `.tgz` archives remain unchanged and require external FFprobe.
Python 3.11+ is required on the build host only.
The protocol-1 hook `scripts/prepare-release.py` uses the publisher's output and
cache directories, copies FFprobe/notices and emits a hashed file manifest. It
never guesses Cargo output paths or creates archives. The publisher handles
archive validation, checksums and upload. See the upstream
[named-bundle contract](https://proxy.dandaedre.com/gitea/idle-org/rust_realease/raw/branch/main/docs/portable-bundles.md).
`crates/pptx-reporter/ffprobe-pins.json` pins a dated BtbN release, exact non-shared
LGPL 9.0 asset name and published SHA-256 digest per target. Dated assets have
versioned names, unlike the downloader's default `latest` assets. To update,
review the provider release and its notices, then update all three fields together.
These dated releases are not marked immutable by GitHub; digest verification
fails closed if an asset changes. Metadata access is still needed with a warm cache.
```sh
rust_realease . --package pptx-reporter --target x86_64-unknown-linux-gnu --compile-only
```
Dry-run validates static configuration without downloads. Compile-only prepares
and packages bundles without a token, tag creation, push or publication. After a
successful invocation, read `dist/latest-artifacts.json`; resolve its `manifest`
and `checksums` paths relative to `dist/`. Resolve assets relative to the resulting
`artifact-manifest.json` directory and verify `SHA256SUMS`. Do not guess build paths.
Before publication, extract both portable trees. On Linux, generate a report using
adjacent FFprobe without relying on PATH. On Windows, launch the GUI and generate
a report without separately installed FFmpeg or Python. Cross compilation and
fixture tests do not replace native acceptance tests. Keep the standalone packager
until those checks are complete. Jenkins remains checks/coverage/badges only.
## Application artwork
Artwork and fonts live in `crates/pptx-reporter/assets/`. Builds embed the PNG
window icon and the ICO Windows resource without image conversion tools.
To regenerate derivatives with ImageMagick from that directory:
```sh
magick rust-report.png -resize 256x256 -background none -gravity center \
-extent 256x256 rust-report-icon.png
magick rust-report-icon.png -define icon:auto-resize=256,128,64,48,32,24,16 rust-report.ico
```