beffroi-tools/docs/development/releases.md

241 lines
12 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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 Windows/macOS ZIPs and a 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 Windows/Linux 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. Pinned cached binaries and notices are rechecked locally before any network access;
unpinned downloads still refresh upstream metadata.
```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.
## macOS
Release builds include `aarch64-apple-darwin` (Apple Silicon) and
`x86_64-apple-darwin` (Intel), with macOS 13.0 as the minimum. Choose the
**portable ZIP** for your Mac. It contains `pptx-reporter`, `pptx-reporter-gui`,
FFprobe, notices and a quick-start guide. Extract the entire archive, then run
`./pptx-reporter-gui` in Terminal, or:
```sh
./pptx-reporter presentation.pptx --report all
```
Keep FFprobe beside the applications. No separate FFmpeg, Python, PowerPoint
or PDF compiler is needed. The smaller canonical cargo-binstall TGZs contain
only the reporter applications and still require external FFprobe.
These are separate architecture-specific executables, not universal binaries
or Finder `.app` bundles. They are not Developer ID signed or notarized.
If macOS blocks a trusted release, open Terminal in the extracted folder:
```sh
xattr -d com.apple.quarantine pptx-reporter pptx-reporter-gui ffprobe
chmod +x pptx-reporter pptx-reporter-gui ffprobe
./pptx-reporter-gui
```
An attribute-not-found message means that file is already unquarantined.
Native startup, file dialogs, drag/drop, report generation and Gatekeeper
behavior still require testing on compatible Macs.
### Bundled macOS FFprobe
`scripts/build_macos_ffprobe.py` builds FFprobe from the exact official source
archive and SHA-256 pinned per Mac target in `ffprobe-pins.json`. It uses the
same digest-pinned cargo-zigbuild image as the reporter, enables local file
probing, and disables network input and external codec-library autodetection.
It does not enable GPL or nonfree components. The dependency is a separate
LGPL executable with statically linked FFmpeg libraries and only macOS system
libraries loaded dynamically.
The source build needs Linux, Python 3.11+, and Podman or Docker (selected via
`CROSS_CONTAINER_ENGINE`, or Podman if available). The image must be available
to the engine. Compilation runs with container networking disabled; downloading
the pinned source occurs first on the host. First preparation can take several
minutes. The cache identity covers the source pin, target, image and recipe;
reused payloads have their hashes and Mach-O compatibility checked. A warm
cache needs no dependency download.
Each Mac portable ZIP includes the complete FFmpeg source archive, LGPL license,
reproduction scripts and `BUILDING.txt` under `LICENSES/ffmpeg/`. The dependency
validator checks the CPU, macOS minimum and system-only library paths without
running foreign binaries. The publisher must include Mach-O support for named
bundle executables, in addition to its existing macOS build support.
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](https://proxy.dandaedre.com/gitea/idle-org/rust_realease/raw/branch/main/docs/automated-macos-releases.md).
```sh
# 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, including the bundled FFprobe. 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
All three Rust apps embed their own PNG window icon and Windows ICO resource,
including CLI-only Windows builds. Linux/FreeBSD X11 uses the window icon;
Wayland desktops match each app ID to its desktop entry. macOS uses the ICNS
resource in an app bundle. A bare Unix executable has no Finder/application-menu icon.
Five coordinated icons were generated with the built-in ImageGen tool. The
[exact prompts](icon-prompts.json) are retained. Each Rust crate keeps its
`app-icon-source.png`, `app-icon.png`, `app-icon.ico` and `app-icon.icns` in
`assets/`. Python artwork lives in `tools/assets/exporter/`; Companion artwork lives in
`companion-modules/media-player-classic/companion/assets/`. Earlier reporter and
converter artwork remains available under its original filenames.
Builds consume committed derivatives and need no image tools. To regenerate the
256px PNG, seven-size ICO (16–256px), and ICNS (128–1024px), install ImageMagick 7
and run `python3 scripts/build-icons.py` from the repository root.
### Desktop launchers
After building or extracting a release, create a launcher pointing to the binary
at its permanent location. The helper refuses existing launchers/icons. Linux/BSD launchers reference the
original executable and stop working if it moves. macOS bundles copy the binary
and adjacent LICENSES directory. Reporter bundles also copy an adjacent FFprobe
(requiring its LICENSES directory); otherwise FFprobe must be on PATH. Recreate
macOS bundles after updating binaries.
```sh
# Linux / FreeBSD: install into your desktop's user application directory.
python3 scripts/create-desktop-launcher.py ascii-names \
--binary "$PWD/target/release/ascii-names" --output "$HOME/.local/share"
# macOS: create a Finder/Dock launcher (run on the Mac).
python3 scripts/create-desktop-launcher.py ascii-names --platform macos \
--binary "$PWD/target/release/ascii-names" --output "$HOME/Applications"
```
The same helper supports `pptx-reporter` and `rundown-converter`; pass their
`-gui` executable. Reporter and rundown portable archives include the helper,
its supporting module, and the icon formats, so these commands also work from
an extracted archive. Respect `XDG_DATA_HOME` instead of `~/.local/share` when
customized. Desktop menus may need a refresh. Windows executables have embedded
icons; shortcuts inherit those icons.
Python scripts and the Companion module run inside a host application and cannot
replace its OS icon. Their PNG/ICO/ICNS files are available for custom shortcuts;
the Companion README displays its module icon. Shared libraries, CI scripts,
packaging helpers and `progress.py` are not standalone applications.
Launcher output is described in [the desktop launcher contract](../interfaces/desktop-launchers.md).
Automated checks validate icon containers and launcher output on Linux. Finder,
Dock, Windows Explorer/taskbar and individual Wayland desktop behavior still
need native visual checks. The macOS launchers are not signed or notarized.
## Releases containing both tools
The workspace version applies to both tools. Build the reporter with the root
configuration, and the converter with its overlay (which omits FFprobe):
```sh
rust_realease . --package pptx-reporter --compile-only
rust_realease . --package rundown-converter --config rust-release-rundown.toml --compile-only
```
Publish both packages' canonical and portable archives under the same version
tag. Aggregate their checksum lists into one `SHA256SUMS`; do not replace one
package's checksums with the other's. Each archive includes both CLI and GUI.