Pedro M. de Echanove Pasquin
806dee5167
Length::dp no longer collapses to absolute pixels at construction: the design value travels in a new LengthBase::Dp variant and the density multiplication happens when the length is resolved. Previously dp( n ) baked in whatever density() returned at view-build time, so correctness across output changes depended on the view being rebuilt after set_density and in that order; now a density change is picked up by the very next paint with no reconstruction. Length::resolve keeps its signature (process density), and the new Length::resolve_with_density takes an explicit factor. dp becomes const in the bargain. Density also becomes overridable per canvas, the first step towards surface-local responsive state. SoftwareCanvas and GlesCanvas carry a density: Option<f32> analogous to the layout_viewport introduced for sub-canvas fluid resolution: None means "use the process global", Canvas::set_density pins a local factor, and sub-canvases inherit it. All canvas-routed resolution honours it — geom_px / font_px for stock-widget design pixels, and the new Canvas::resolve_geom / resolve_font for explicit Length values, which every widget now uses in place of the raw l.resolve( canvas.viewport_layout(), EM ) pattern (row, column, wrap_grid, spacer, container, separator, button, text, rich_text, text_edit, list_item, vslider, image, and the container draw path). Overlay sizing keeps resolving against the main surface with the global density, which is what it describes. New tests cover explicit-density resolution, resolution-time application, the local-over-global override and sub-canvas inheritance. The GLES image texture cache is now bounded. It was content-keyed but unbounded and never evicted, so a stream of distinct buffers — a photo carousel, video thumbnails — grew GPU memory for the lifetime of the canvas. The cache now tracks an estimated byte total (RGBA8, w × h × 4) against a 32 MiB budget and evicts least-recently-drawn textures on insert; the most recent entry is never evicted, so a single texture larger than the whole budget still draws and simply owns the cache until replaced. Drop-time cleanup is unchanged: drain deletes whatever the map holds. CI gains a Clippy step (workspace, all targets, test-support, -D warnings) sharing the build cache of the test job, with make clippy mirroring the invocation locally and CONTRIBUTING listing it. Run make clippy locally before pushing the first time — the gate has not seen the tree yet and pre-existing lints will fail CI until addressed. docs/backends.md formalises the software/GLES capability matrix that was previously scattered across per-method rustdoc: parity set (fills, strokes, text, images, paths, path clips), graceful degradations on software (flat-fill gradients, no shadows, no backdrop blur, hard bottom edge), GPU-only features (external textures), the shared Oklab-fallback limitation, and the cross-backend blit panic. Linked from README, onboarding and architecture's known-gaps list, which now states the parity gaps explicitly. The dp/density prose in architecture.md, lib.rs and the Length rustdoc is updated for resolution-time semantics and the per-canvas override.
151 lines
5.9 KiB
Markdown
151 lines
5.9 KiB
Markdown
# Contributing to ltk
|
|
|
|
Thanks for considering a contribution. This document covers the practical
|
|
mechanics: how to set up your environment, how to run tests, what shape a
|
|
patch should take, and where to send it.
|
|
|
|
For background on the toolkit itself, read
|
|
[`docs/onboarding.md`](docs/onboarding.md) and
|
|
[`docs/architecture.md`](docs/architecture.md) first.
|
|
|
|
## Reporting bugs and proposing features
|
|
|
|
Open an issue on the project repository before sending a non-trivial
|
|
patch. We want to align on scope before you spend time on an
|
|
implementation. For security-relevant issues see
|
|
[`SECURITY.md`](SECURITY.md) — those should *not* go through the public
|
|
issue tracker.
|
|
|
|
When reporting a bug, include:
|
|
|
|
- the `ltk` version (commit hash if you built from source),
|
|
- the Rust toolchain (`rustc --version`),
|
|
- the compositor and OS,
|
|
- a minimal reproducer (Rust source preferred over screenshots),
|
|
- whether the issue happens on both the GLES and the software backend
|
|
(set `LTK_FORCE_SOFTWARE=1` to force software).
|
|
|
|
## Building and testing
|
|
|
|
The project requires the Rust toolchain shipped with Debian stable
|
|
(currently 1.85). On Debian / Ubuntu:
|
|
|
|
```bash
|
|
sudo apt-get install \
|
|
libwayland-dev libegl-dev libxkbcommon-dev pkg-config
|
|
|
|
git clone <repo>
|
|
cd ltk
|
|
cargo build
|
|
cargo test --features test-support
|
|
```
|
|
|
|
Tests require the `test-support` feature: the `test_support` module is
|
|
feature-gated in `src/lib.rs`, and the code under `tests/` and
|
|
`benches/` imports it, so a bare `cargo test` fails to compile.
|
|
|
|
The `Makefile` wraps the common targets:
|
|
|
|
```bash
|
|
make all # cargo build --release
|
|
make test # cargo test --features test-support
|
|
make doctest-md # typecheck the Rust snippets in docs/*.md
|
|
make stylecheck # mechanical style checks (tabs, attribute spacing)
|
|
make clippy # semantic lints, warnings as errors (mirrors CI)
|
|
make audit # cargo audit (installs cargo-audit on first run)
|
|
make doc # cargo doc --no-deps
|
|
make examples # run every example under examples/ in turn
|
|
make clean # runs dh_clean, so it needs debhelper installed
|
|
```
|
|
|
|
Run `make doctest-md` after editing any file under `docs/` — it feeds
|
|
each markdown file to `rustdoc --test` to catch API drift in the
|
|
snippets.
|
|
|
|
Running the examples requires a Wayland session and the default theme
|
|
on disk:
|
|
|
|
```bash
|
|
export LTK_THEMES_DIR="$PWD/themes"
|
|
cargo run --example showcase
|
|
```
|
|
|
|
## Code style
|
|
|
|
`ltk` uses a custom **Modified Allman** style. `rustfmt`'s default
|
|
settings do not match it; do not run `cargo fmt`. The full rules live
|
|
in [`code_style_guide.md`](code_style_guide.md), but the headline points
|
|
are:
|
|
|
|
- **tabs** for indentation (never spaces),
|
|
- opening `{` on its **own new line** for `fn`, `impl`, `struct`,
|
|
`enum`, `mod`, `if`, `for`, `while`, `match`, `loop`,
|
|
- `} else {` and `} else if … {` on the same line as the closing brace
|
|
(compact else),
|
|
- spaces inside non-empty parentheses: `fn foo( x: i32 )`,
|
|
`bar( arg )`, `Some( x )`, `Ok( v )`,
|
|
- spaces inside non-empty attribute brackets: `#[ derive( Clone, Debug ) ]`,
|
|
- no spaces inside `<>` generics: `Vec<String>`, `Option<i32>`,
|
|
- comments in **English** — never another language.
|
|
|
|
Match the surrounding code when in doubt.
|
|
|
|
## Patch shape
|
|
|
|
- Keep changes focused: one logical change per pull request. A bug fix
|
|
and a refactor go in separate PRs.
|
|
- Add tests. The repository has ~680 tests covering the existing
|
|
surface, and a contribution that adds behaviour without test
|
|
coverage will get review pushback. See [`tests/`](tests/) for
|
|
examples of integration tests via `UiSurface`, and the inline
|
|
`#[cfg(test)] mod tests` blocks under `src/` for unit tests.
|
|
- Document new public API. Every `pub` item exported from the crate
|
|
root is expected to have a `///` rustdoc comment with at minimum a
|
|
one-paragraph description and an example. Module-level `//!`
|
|
comments are required for new submodules.
|
|
- Don't break the public API surface without coordinating. Until the
|
|
crate hits `1.0`, breaking changes go in minor versions
|
|
(`0.x.0 → 0.(x+1).0`); patch versions (`0.x.y → 0.x.(y+1)`) keep
|
|
source compatibility.
|
|
- Give user-visible changes a `CHANGELOG.md` entry under
|
|
`[Unreleased]`.
|
|
- Run `cargo test --features test-support` and `make audit` before
|
|
sending. CI will run them
|
|
again, but it is faster for both of us if your local run is clean.
|
|
|
|
## Architectural decisions worth knowing
|
|
|
|
A few patterns recur across the codebase:
|
|
|
|
- **Builder methods consume `self`** (`pub fn padding( mut self, p: impl Into<Length> ) -> Self`).
|
|
Chaining works because every builder returns `Self`. Don't introduce
|
|
setters that take `&mut self`.
|
|
- **Layouts and widgets share `Element<Msg>`.** Anything that converts
|
|
to `Element` can be pushed into any layout. The split between
|
|
[`src/layout/`](src/layout/) and [`src/widget/`](src/widget/) is
|
|
documentation, not architecture.
|
|
- **The runtime is single-threaded.** Use `RefCell` for caches inside
|
|
`App` state, never `Mutex`. Cross-thread communication goes through
|
|
[`ChannelSender`](src/app.rs).
|
|
- **`view()` must be pure.** No I/O, no allocation-heavy work, no
|
|
state mutation. Cache derived data on the app struct (behind
|
|
`RefCell` if needed) and look it up.
|
|
- **Theming is process-global.** There is no per-app theme; the active
|
|
document and mode live in a `RwLock<Arc<…>>`. `view()` reads the
|
|
state, never writes it. Mode flips and document swaps go through
|
|
`ltk::set_active_mode` and `ltk::set_active_document`.
|
|
- **Per-frame allocations are fine.** Building the `Element` tree on
|
|
every render is the supported model. Don't try to retain widgets
|
|
across frames.
|
|
|
|
## License
|
|
|
|
By submitting a patch you agree it is licensed under
|
|
[`LGPL-2.1-only`](LICENSE), the same as the rest of the project. Do not
|
|
add `Co-Authored-By` lines or other AI attribution to commit messages.
|
|
|
|
## Code of conduct
|
|
|
|
Be respectful. Disagreements are welcome; personal attacks are not.
|
|
Maintainers will moderate threads that go off the rails.
|