beffroi-tools/docs/releases.md

7.4 KiB

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.

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:

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:

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.

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.

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.

macOS

Release builds include aarch64-apple-darwin (Apple Silicon) and x86_64-apple-darwin (Intel), with macOS 13.0 as the minimum. Each canonical TGZ contains pptx-reporter and pptx-reporter-gui. Extract the matching archive and run ./pptx-reporter-gui, or:

./pptx-reporter presentation.pptx --report all

Supply a macOS FFprobe executable beside the reporter, under its bin/ directory, or on PATH. The pinned BtbN downloader and named portable bundle currently cover Windows and Linux only. macOS archives contain no FFprobe. PDF compilation and fonts remain embedded.

These are separate architecture-specific executables, not universal binaries or Finder .app bundles. They are not Developer ID signed or notarized; Gatekeeper may require user approval before launch. Native startup, file dialogs, drag/drop, report generation and Gatekeeper behavior still require testing on compatible Macs.

On the Linux release host, the same publisher routes Apple targets through the digest-pinned cargo-zigbuild image in [build.apple]; Cross remains responsible for Windows/Linux. No host Xcode or Darwin Cross image is used. The image pin, SDK path and deployment minimum are explicit in rust-release.toml. See the upstream automated macOS workflow.

# Validate the complete four-target release configuration.
rust_realease . --package pptx-reporter --dry-run
# Build/package just the two macOS architectures, without publication.
rust_realease . --package pptx-reporter \
  --target aarch64-apple-darwin --target x86_64-apple-darwin --compile-only
# Build/package the complete release, including Windows/Linux portable bundles.
rust_realease . --package pptx-reporter --compile-only

Review SHA256SUMS and archive executable modes. The publisher checks Mach-O architecture, the exact macOS deployment minimum and system-only dynamic dependencies. Foreign cargo-binstall checks install files without executing them; macOS runtime validation is explicitly skipped on Linux. Publish the complete configured matrix together so its checksum manifest covers all platforms.

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:

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