GUI-free half of the cce toolkit: config, input, IPC, spec parsers
git clone https://git.lucas.co/cce-core.git
CLAUDE.md (2.9K)
1 # CLAUDE.md
2
3 This is the `cce-core` crate, the GUI-free half of the cce toolkit. Read the
4 workspace guide `../cce-compositor/WORKSPACE.md` first: the multi-repo layout,
5 the standalone-build rule, `ccebuild`, and the concurrent-sessions rules. This
6 crate is SHARED like `cce-ui`. Run `git status` before editing it, and treat
7 foreign dirt as another session's.
8
9 ## What lives here
10
11 | Module | What it is |
12 |---|---|
13 | `config` | the KDL config: paths (`~/.config/cce`, XDG), reading, writing with rolling backups, the JSON view |
14 | `input` | `input.kdl`: domain-scoped bindings and pointer settings |
15 | `motion` | the DE-wide animations switch (`/run/cce/animations`) |
16 | `units` | lengths with units (`(mm)2.0`) and the display metric |
17 | `ipc` | the `/tmp/<prefix>-<WAYLAND_DISPLAY>.sock` convention, `ipc::instance` (not wasm) |
18 | `color`, `ramp`, `relief_spec`, `droplet` | the parsers for the specs the DE writes: hex colours, ramp curves, relief, droplets |
19 | `locale` | the user's locale as a BCP 47 tag (`LC_ALL`, `LC_CTYPE`, `LANG`; the browser's `navigator.language`) |
20 | `l10n` (feature) | message catalogues in Project Fluent's format: a domain's English built in, translations found as `<tag>/<domain>.ftl` under `CCE_LOCALE_DIR`, `$XDG_DATA_HOME/cce/locale`, `$XDG_DATA_DIRS/*/cce/locale` |
21
22 The `l10n` feature is off by default: a process that shows no text (the
23 compositor, `cce-window-manager`) does not carry fluent-bundle; cce-ui turns it
24 on. Under `cfg(test)` / `test-isolation` it reads no translation directory.
25
26 `cce-ui` re-exports every module at its old path (`cce_ui::config`,
27 `cce_ui::motion`, `cce_ui::scene::paint::DropletSpec`, `cce_ui::layout::sample_ramp_keys`,
28 …), so apps never name this crate. A process that does not draw (the compositor,
29 a sync daemon, a CLI helper) depends on it directly and links none of the
30 toolkit's Wayland, Vulkan or text stack. Nothing here may depend on cce-ui; that
31 is the point of the split.
32
33 ## The test-isolation feature
34
35 Several functions answer differently under `cfg(test)`, so a suite never reads
36 the machine. `config::config_home()` is a per-process directory nobody creates,
37 `input::natural_scroll()` reads false, and `motion::enabled()` is on unless
38 `motion::force_for_test` says otherwise. Since those modules live here,
39 `cfg(test)` would only cover this crate's own suite. Every such gate is
40 `cfg(any(test, feature = "test-isolation"))` instead, and cce-ui turns the
41 feature on through its dev-dependency. Resolver 2 keeps it out of normal builds,
42 and a dependent's test build that does not build cce-ui's dev-dependencies does
43 not get it either, which is what those builds had before the split.
44
45 ## Build, test
46
47 ```sh
48 cargo test -p cce-core
49 cargo test -p cce-core --features test-isolation
50 cargo test -p cce-core --features l10n
51 ```
52
53 The crate builds for `wasm32-unknown-unknown` too (minus `ipc`), as cce-ui does.
54 After pushing, run `../bump-revs.sh cce-core` to repin cce-ui and the compositor.