43 lines
3.0 KiB
Markdown
43 lines
3.0 KiB
Markdown
# AI Agent & Contributor Guidelines: Rust Dependency & Feature Minimization
|
|
|
|
## Core Principle: Minimal Features & Fast Compilation
|
|
|
|
To ensure fast compilation times and prevent binary and dependency bloat on development and embedded/kiosk hardware:
|
|
|
|
1. **Always use `default-features = false` by default** on all external crates unless explicitly proven unnecessary.
|
|
2. **Never enable meta-features or "all" feature flags**:
|
|
- ❌ Never use `tokio = { features = ["full"] }`.
|
|
- ❌ Never use `egui_extras = { features = ["all_loaders"] }`.
|
|
- ❌ Never enable default formats in the `image` crate (pulls in `rayon`, `exr`, `tiff`, `dds`, `hdr`, etc.).
|
|
3. **Avoid heavy rasterization / rendering stacks**:
|
|
- Do **NOT** enable `svg` or `resvg` in `egui_extras`. The `resvg`/`usvg`/`tiny-skia` dependency tree adds dozens of crates and heavily impacts compilation time.
|
|
- Do **NOT** enable `wgpu` in `eframe`. Use `glow` (OpenGL) only.
|
|
4. **Iterate with `cargo check`**:
|
|
- Always run `cargo check` instead of `cargo build` during development cycles to test type checking and borrow checking in seconds.
|
|
|
|
---
|
|
|
|
## Approved Dependency Feature Matrix
|
|
|
|
When editing or updating `jellyfin-kiosk-rs/Cargo.toml`, adhere strictly to the following configurations:
|
|
|
|
| Crate | Approved Configuration | Rationale / Prohibited Features |
|
|
| :--- | :--- | :--- |
|
|
| `eframe` | `default-features = false, features = ["default_fonts", "glow", "wayland", "x11"]` | Keep `wgpu` disabled. Only build necessary windowing and OpenGL backends. |
|
|
| `egui_extras` | `default-features = false, features = ["http", "image"]` | Only needed for fetching/rendering HTTP posters & backdrops. **Never enable `all_loaders` or `svg`**. |
|
|
| `image` | `default-features = false, features = ["jpeg", "png"]` | Jellyfin images are JPEGs/PNGs. Disabling default features avoids `rayon` and heavy decoders. |
|
|
| `tokio` | `default-features = false, features = ["rt-multi-thread", "macros", "net", "io-util", "sync", "time"]` | Never use `"full"`. `fs`, `process`, and `signal` from Tokio are not used (standard library equivalents are used). |
|
|
| `axum` | `default-features = false, features = ["http1", "json", "tokio"]` | The REST API only handles JSON POST/GET requests and Tokio serving. No `form` or `query` parsers needed. |
|
|
| `reqwest` | `default-features = false, features = ["json", "default-tls", "http2"]` | Minimal HTTP client features required for communication with the Jellyfin server. |
|
|
| `tracing-subscriber`| `features = ["env-filter"]` | Standard lightweight log filtering and formatting. |
|
|
| `rumqttc` | `default-features = false` | MQTT client for Home Assistant discovery and state reporting. Avoids rustls/aws-lc-rs crypto bloat. |
|
|
|
|
---
|
|
|
|
## Verification Before Committing
|
|
|
|
Whenever dependencies or features are changed:
|
|
1. Run `cargo check` in `jellyfin-kiosk-rs` to ensure compilation without warnings/errors.
|
|
2. Check dependency count in `Cargo.lock` (`grep "name = " Cargo.lock | wc -l`) to confirm no unexpected transitive bloat was introduced.
|
|
3. Verify that `cargo build` links successfully.
|