Pedro M. de Echanove Pasquin
a7f953ca42
grid_min_cell( width ) adds the adaptive mode WrapGrid was missing: instead of a fixed column count, the count is derived at layout time from the available width so every cell is at least `width` wide (any Length, so a fluid threshold works; never fewer than one column), re-derived on every resize. Cells then share the width equally, and WrapGrid::max_columns( n ) caps the derived count so cells grow instead of multiplying on very wide surfaces — the cap only applies to the adaptive mode, grid( n ) keeps the fixed behaviour untouched. Four new layout tests cover width derivation, spacing accounting, the one-column floor and the cap; the row-wrap assertions check X positions rather than Y because zero-height spacer children produce zero-height rows. flex( child ) now distributes leftover height inside a Column, mirroring its leftover-width behaviour in a Row: flex children join the weight pool alongside weight-only spacers and y-scrolls, draw their child inside the allocated share at full inner width, and contribute zero to the column's natural height exactly like a row counts flex width. This closes the documented "vertical flex is not yet implemented" gap; the Flex rustdoc and the widgets.md entry now describe both axes. Add scripts/style-check.sh and a make stylecheck target, wired into CI: mechanical verification of the grep-checkable subset of code_style_guide.md — tab indentation and spaces inside attribute brackets — with comment lines skipped so prose may cite raw attribute syntax. To turn the check on green, the 82 unspaced attribute sites across 24 files (#[test], #[derive(...)], #[cfg(...)], #[allow(...)]) were normalized to the spaced form. CONTRIBUTING and the style guide reference the new target; brace placement and paren spacing remain review concerns.
150 lines
5.8 KiB
Markdown
150 lines
5.8 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 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.
|