48 lines
2.0 KiB
Markdown
48 lines
2.0 KiB
Markdown
# Development
|
|
|
|
## Layout and workflow
|
|
|
|
| Directory | Purpose |
|
|
| --- | --- |
|
|
| `tools/` | Python prototypes and document utilities |
|
|
| `tests/` | Python regression and CI/packaging tests |
|
|
| `crates/<tool>/` | Rust ports, each with its own source, tests and assets |
|
|
| `scripts/` | Shared CI, parity and release helpers |
|
|
| `docs/` | Tool usage and specialized workflows |
|
|
|
|
Prototype in Python, then add a Rust workspace member when the workflow is
|
|
stable. Keep the Python implementation as a parity reference while useful.
|
|
Avoid speculative shared crates; extract common code when multiple tools need it.
|
|
|
|
The root `Cargo.toml` owns workspace metadata, the shared version and build
|
|
profiles. Members inherit that metadata. Keep one root `Cargo.lock` and `target/`.
|
|
The reporter is the default member; CI explicitly checks the entire workspace.
|
|
Use `-p pptx-reporter` to select it when building from a multi-tool workspace.
|
|
|
|
## Checks
|
|
|
|
Use a recent stable Rust toolchain. Python tools need 3.9+; CI helpers need 3.11+.
|
|
Run from the repository root:
|
|
|
|
```sh
|
|
cargo fmt --all --check
|
|
cargo clippy --locked --workspace --all-targets --all-features -- -D warnings
|
|
cargo test --locked --workspace --all-features
|
|
RUSTDOCFLAGS="-D warnings" cargo doc --locked --workspace --all-features --no-deps
|
|
python3 -m unittest discover -s tests -v
|
|
cargo build --locked --workspace --all-features
|
|
python3 scripts/parity.py target/debug/pptx-reporter
|
|
```
|
|
|
|
Parity requires FFmpeg, FFprobe and the Typst CLI for the Python reference.
|
|
It compares JSON/Ontime for real media with trims, loops, custom timing and
|
|
orphan media, and generates every report format. Python exporter tests mock
|
|
external document applications. Inspect rendering changes visually as well.
|
|
|
|
`cargo build -p pptx-reporter --no-default-features` builds the CLI without the
|
|
GUI or PDF engine; add `--features pdf` to restore embedded PDFs.
|
|
|
|
Keep generated files out of Git. Commit each completed task after checks; do
|
|
not push without authorization. See [CI and coverage](ci.md) and
|
|
[cross builds and packaging](releases.md).
|