208 lines
10 KiB
Markdown
208 lines
10 KiB
Markdown
# Rust PPTX reporter trial
|
|
|
|
The `feature/rust-reporter` branch ports the reporter only. The Python reporter
|
|
remains a regression reference; `tools/exporter.py` is unchanged.
|
|
The core parses PPTX XML/ZIP, discovers video references in presentation order,
|
|
extracts/probes media, applies per-shape trims, and writes HTML, Markdown, TXT,
|
|
JSON, Typst, PDF, dense PDF and Ontime. Defaults remain Markdown + Ontime.
|
|
|
|
## Desktop and CLI
|
|
|
|
```sh
|
|
cargo run --locked --bin pptx-reporter-gui
|
|
cargo run --locked --bin pptx-reporter -- presentation.pptx --timings-only --report all
|
|
cargo run --locked --bin pptx-reporter -- presentation.pptx --extract-only
|
|
```
|
|
|
|
Drop one PPTX into the window or use the file picker. Choose the output folder,
|
|
extraction mode and report formats, then Generate. The app remembers options and
|
|
the last eight presentations. Advanced settings contain overwrite and FFprobe
|
|
location controls. Result actions open reports/folders and copy file paths.
|
|
Progress, warnings and an expandable activity log remain visible. Estimates
|
|
apply to the current counted phase; PDF compilation is an indeterminate step.
|
|
Cancel interrupts FFprobe and is checked between extraction/report steps; an
|
|
in-progress Typst compilation finishes before cancellation is observed.
|
|
|
|
`pptx-reporter-gui.exe` uses Windows' windowed subsystem (no terminal).
|
|
`pptx-reporter.exe` is the CLI; without arguments it also opens the GUI.
|
|
PDF compilation uses pinned Typst 0.13 crates and bundled DejaVu Sans regular/bold
|
|
fonts. It reads no external Typst files, downloads no packages and needs no
|
|
`typst.exe`. FFprobe is discovered beside the application, under its `bin/`
|
|
directory, or on PATH; `--ffprobe PATH` overrides discovery.
|
|
|
|
Output stays in `<presentation>_videos/videos` and `reports`. Existing extracted
|
|
media is reused unless `--overwrite` is set; reports are regenerated. Empty
|
|
presentations create no output. Unknown metadata is reported without inventing
|
|
durations. Loops/custom timing remain visible and are absent from Ontime.
|
|
Extracted media remains unchanged. See [report semantics](pptx-videos.md).
|
|
|
|
## Development and checks
|
|
|
|
Use a recent stable Rust toolchain and retain `Cargo.lock`. The desktop build
|
|
supports X11/Wayland on Linux and Windows. On Linux, windowing/OpenGL libraries
|
|
must be present at runtime. `--no-default-features` builds the CLI/core without
|
|
desktop or PDF dependencies; `--features pdf` restores embedded PDF generation.
|
|
|
|
```sh
|
|
cargo fmt --check
|
|
cargo clippy --locked --all-targets --all-features -- -D warnings
|
|
cargo test --locked --all-features
|
|
RUSTDOCFLAGS="-D warnings" cargo doc --locked --all-features --no-deps
|
|
python3 -m unittest discover -s tests -v
|
|
cargo build --locked --all-features
|
|
python3 scripts/parity.py target/debug/pptx-reporter
|
|
```
|
|
|
|
Parity checks require FFmpeg, FFprobe and the Typst CLI for the Python reference.
|
|
They build a synthetic presentation with real media, shared clips, distinct
|
|
trims, loops, invalid/custom timing and orphan media; both implementations must
|
|
produce identical report JSON and Ontime projects and generate all formats.
|
|
Visual layouts are deliberately preserved in appearance rather than comparing
|
|
PDF bytes or requiring identical markup.
|
|
|
|
## Cross and release preparation
|
|
|
|
`Cross.toml` configures Windows GNU x64 and Linux GNU x64 with Cross's `main`
|
|
images. Linux GNU is intentional for the desktop app; a fully static musl GUI
|
|
is not promised. Cross needs a working Docker or Podman backend.
|
|
No release action is run by Jenkins.
|
|
Release metadata follows the
|
|
[`rust_realease` contract](https://proxy.dandaedre.com/gitea/idle-org/rust_realease).
|
|
|
|
```sh
|
|
cross build --locked --release --target x86_64-pc-windows-gnu
|
|
cross build --locked --release --target x86_64-unknown-linux-gnu
|
|
rust_realease . --package pptx-reporter --dry-run
|
|
rust_realease . --package pptx-reporter --compile-only
|
|
```
|
|
|
|
The package metadata matches `rust_realease`'s cargo-binstall archive contract.
|
|
`rust-release.toml` maps the SSH origin host to the public HTTPS Gitea repository.
|
|
Version comes only from `Cargo.toml`; a future publication needs a matching
|
|
explicitly created/pushed tag and a clean checkout. Dry-run reports a missing
|
|
tag as a prerequisite, even while previewing this untagged feature branch.
|
|
No tag or release is created as part of this trial.
|
|
|
|
`rust_realease` archives contain Cargo binaries only. Its current documented
|
|
configuration has no arbitrary packaging hook. Release automation can call the
|
|
portable packager after the Cross builds above; it fetches FFprobe on demand:
|
|
|
|
```sh
|
|
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 [upstream packaging task](fix-rust-realease.task.md) specifies the hooks,
|
|
runtime-file inclusion and portable artifact support needed to replace this
|
|
separate packaging step with the normal `rust_realease` workflow.
|
|
|
|
This creates a ZIP under `dist/`, with both reporter binaries, FFprobe,
|
|
licences, download provenance, quick-start instructions and a SHA-256 checksum
|
|
(Linux uses `.tar.gz`). These commands expect the reporter binaries under
|
|
`target/<target>/release/`. `rust_realease` can use a separate build directory
|
|
for dirty checkouts; use the explicit Cross commands above for these paths.
|
|
|
|
The standalone downloader is also callable from a release script:
|
|
|
|
```sh
|
|
python3 scripts/fetch_ffprobe.py --target x86_64-pc-windows-gnu
|
|
```
|
|
|
|
It selects BtbN's **FFmpeg 9.0 release-branch, non-shared LGPL** builds,
|
|
checks the archive against the SHA-256 reported by GitHub's release API,
|
|
and validates PE/ELF format and x86-64 machine type. On a matching host it also
|
|
runs `ffprobe -version` before installing the cache entry. Foreign executables
|
|
are inspected without execution. Downloads are temporary; the extracted
|
|
binary, upstream notices, and provenance are cached under ignored
|
|
`downloads/ffprobe/<target>/<archive-sha256>/`. Cached file hashes are verified
|
|
on reuse. A failed download/check does not install a cache entry.
|
|
|
|
The default upstream tag `latest` moves. For repeatable release builds, pass
|
|
`--ffprobe-release TAG --ffprobe-sha256 HASH` to the packager (or `--release TAG
|
|
--sha256 HASH` to the downloader). Provenance records the release/asset IDs,
|
|
download URL and digest. A missing asset or mismatched digest fails rather
|
|
than silently choosing another build. GitHub API rate limits/network failures
|
|
are errors; a previously cached download does not bypass metadata verification.
|
|
|
|
[BtbN's compatibility notes](https://github.com/BtbN/FFmpeg-Builds#readme)
|
|
specify Windows 10 22H2 or newer, and Linux glibc 2.28/kernel 4.18 or newer.
|
|
These builds are linked from [FFmpeg's download page](https://ffmpeg.org/download.html).
|
|
For another provider or offline packaging, supply a standalone target binary:
|
|
|
|
```sh
|
|
python3 scripts/package-portable.py --target x86_64-pc-windows-gnu \
|
|
--ffprobe /path/to/ffprobe.exe --ffprobe-licenses /path/to/notices
|
|
```
|
|
|
|
No FFprobe binary is committed. Only the downloader and packaging code are
|
|
versioned; `downloads/`, `target/` and `dist/` are ignored.
|
|
The app/report fonts are already embedded. Do not describe a binary-only
|
|
`rust_realease` archive as the complete portable distribution.
|
|
|
|
A Windows validation machine should check launching without a console, real
|
|
file drops, file dialogs, Unicode paths, scaling, opening results, and the
|
|
bundled FFprobe. Building successfully on Linux does not establish those checks.
|
|
Signing and an installer are optional follow-up distribution work.
|
|
|
|
## Coverage and mutable badges
|
|
|
|
The workflow implements the
|
|
[coverage-badge task](https://proxy.dandaedre.com/gitea/Dandaedre/agent-tasks/raw/branch/main/tasks/ci-coverage-badges.task.md).
|
|
|
|
CI uses Python 3.11+ for the standard-library TOML reader. Install exactly
|
|
`cargo-llvm-cov 0.9.1` and the active toolchain's `llvm-tools-preview`.
|
|
The exact measurement command is:
|
|
|
|
```sh
|
|
cargo llvm-cov --locked --all-features --json --summary-only --output-path coverage/summary.json
|
|
```
|
|
|
|
`cargo coverage` is an alias for that command. To run the actual gate and
|
|
diagnostics, use:
|
|
|
|
```sh
|
|
python3 scripts/ci.py init
|
|
python3 scripts/ci.py coverage
|
|
python3 scripts/ci.py finalize
|
|
```
|
|
|
|
The initial trial floor is **75% line coverage**, defined in `coverage.toml`.
|
|
The GUI/event loop and both binaries remain in the denominator; there are no
|
|
production-code exclusions. This is a baseline for the trial, not a claim of
|
|
complete UI automation. Measurement uses the unrounded covered/count ratio.
|
|
The temporary `coverage/summary.json` is removed after diagnostics/badge
|
|
processing, including on gate failure. Fresh below-floor coverage survives
|
|
cleanup; unavailable measurements become neutral `-%`.
|
|
|
|
Version comes from `Cargo.toml`. Test status comes only from the current
|
|
`BUILD_NUMBER` marker created after Python tests, Rust tests and parity pass.
|
|
The Jenkins job must be a **Multibranch Pipeline** providing `BRANCH_NAME`;
|
|
the Tools stage enforces its presence. Actual job configuration is an external
|
|
deployment checkpoint and must be verified by the Jenkins administrator.
|
|
|
|
Cleanup generates and archives exactly `coverage/version.svg`,
|
|
`coverage/test.svg`, and `coverage/coverage.svg` with fingerprinting.
|
|
Only non-PR `main` builds publish those files under:
|
|
|
|
```text
|
|
/mnt/assets/coverage/Beffroi/beffroi-tools/main/
|
|
```
|
|
|
|
Public badge URLs:
|
|
|
|
- https://assets.dandaedre.com/coverage/Beffroi/beffroi-tools/main/version.svg
|
|
- https://assets.dandaedre.com/coverage/Beffroi/beffroi-tools/main/test.svg
|
|
- https://assets.dandaedre.com/coverage/Beffroi/beffroi-tools/main/coverage.svg
|
|
|
|
The renderer comes from `Dandaedre/agent-tasks` revision
|
|
`8923682b958de698c5ec41f4275bfc6f7e44a2f6`. Generated badges, markers and summaries
|
|
are ignored. Tests exercise renderer validation/XML, threshold boundaries,
|
|
failure cleanup, publication permissions and old-branch-symlink migration.
|
|
|
|
The external asset server should mount published assets read-only, disable
|
|
directory listings, serve SVG with a restrictive CSP, and revalidate mutable
|
|
URLs or give them a short cache lifetime. Live publication and public retrieval
|
|
must be verified separately; adding README URLs does not make badges live.
|