Files

Pedro M. de Echanove Pasquin 806dee5167

CI / build + test (push) Has been cancelled

Details

CI / cargo audit (push) Has been cancelled

Details

render, types, ci: resolution-time dp with per-canvas density, bounded GLES image cache, clippy gate, backend capability matrix

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.

2026-08-01 10:17:00 +02:00

5.9 KiB

Raw Blame History

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 and 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 — 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:

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:

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:

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, 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/ 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/ and 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.
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, 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.

5.9 KiB Raw Blame History