241 lines
12 KiB
Markdown
241 lines
12 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 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.
|