diff --git a/crates/ui-contract/Cargo.toml b/crates/ui-contract/Cargo.toml index 52f06d3c6..21115e476 100644 --- a/crates/ui-contract/Cargo.toml +++ b/crates/ui-contract/Cargo.toml @@ -16,10 +16,12 @@ workspace = true [features] default = [] -# `craft_ui::testing`: the fixture and suite runner. -testing = ["dep:libtest-mimic"] +# `craft_ui::testing`: the fixture and suite runner, with the snapshot renderer. One feature for all of the test kit, +# so every test build of every crate asks the runtime for the same thing and builds it once; a crate that depends on +# the runtime through another framework crate cannot name the runtime's features on the command line. +testing = ["dep:libtest-mimic", "snapshot"] # `craft_ui::testing::snapshot`: stories rendered to images offscreen (desktop only). -snapshot = ["testing", "dep:egui_kittest", "dep:image"] +snapshot = ["dep:egui_kittest", "dep:image"] # Draw colour glyphs (COLR, sbix, CBDT), e.g. colour emoji. color_fonts = ["dep:epaint", "epaint/color_fonts"] # Find installed fonts for characters the app's faces lack (desktop only). diff --git a/docs/development.md b/docs/development.md index 960eb2966..5344ecf29 100644 --- a/docs/development.md +++ b/docs/development.md @@ -24,7 +24,7 @@ A fix to one gallery component, from the edit to its old/new picture on a page: ## One fixed feature set -cargo compiles a crate once per distinct feature set it is asked for, and every crate above it once more. Before `cl`, local commands differed in craft-ui's `app` (the gallery), `snapshot` (the sheet), `testing` (the tests) and the domain crates' `screen-testing`, so a target directory held two to five copies of the framework and rebuilt it between one agent's test, gallery and sheet commands. `cl` adds the same features to every command: the crate's test feature (`screen-testing`, else `testing`) plus craft-ui's `app`, `testing` and `snapshot` (for the framework crates themselves: craft-ui-contract's `testing` and `snapshot`, craft-ui-shell's `app`). The proc-macro crate pins syn's and proc-macro2's features to everything other derive crates may add, so the one syn every proc macro shares is the same in every build; craft-ui-contract depends on craft-window with `ui`, so the shell's `app` changes nothing below the shell; and dev-dependency lines ask for no egui features the test kit does not need. +cargo compiles a crate once per distinct feature set it is asked for, and every crate above it once more. Before `cl`, local commands differed in craft-ui's `app` (the gallery), `snapshot` (the sheet), `testing` (the tests) and the domain crates' `screen-testing`, so a target directory held two to five copies of the framework and rebuilt it between one agent's test, gallery and sheet commands. `cl` adds the same features to every command: the crate's test feature (`screen-testing`, else `testing`) plus craft-ui's `app` and `testing` (for the facade and the shell: craft-ui-shell's `app`). The runtime's `testing` includes the snapshot renderer, because a feature can be named on the command line only for a direct dependency, and crates above widgets reach the runtime through other framework crates. The proc-macro crate pins syn's and proc-macro2's features to everything other derive crates may add, so the one syn every proc macro shares is the same in every build; craft-ui-contract depends on craft-window with `ui`, so the shell's `app` changes nothing below the shell; and dev-dependency lines ask for no egui features the test kit does not need. What still differs, by design: a framework crate's own tests have no eframe in their graph, domain crates do; two domain crates can differ in a few of their own dependencies' features; the gallery with every app enables a few more features below the framework. Each of those is one extra framework build in a target directory, once; `cl` names the crate and the feature set whenever it happens. @@ -32,7 +32,9 @@ What still differs, by design: a framework crate's own tests have no eframe in t - `--all-features`: enables `snapshot`, `system_fonts`, `color_fonts`, text's `all-languages` and more, a set no loop uses; it rebuilt 206 dependency crates and every framework crate once. CI runs it. - `--bins` on the gallery: three 1 GB executables nobody opens locally. -- Workspace-wide builds and tests (`--workspace`, `cargo xtask ci`): 43 minutes for the test build alone. The GitHub workflows run the full matrix on every push; locally, build the crate you changed and run its trials. +- Workspace-wide builds and tests (`--workspace`, `cargo xtask ci`): 43 minutes for the test build alone. Locally, build the crate you changed and run its trials; the GitHub workflows cover the rest of what they cover. + +What CI covers today (.github/workflows): `ui.yml` is the framework's gate: clippy and tests of the seven ui crates with and without `--all-features`, and a wasm check of the facade, on every push that touches them; `theme.yml` covers craft-theme and craft-theme-store; `docs.yml` builds the documentation; and some leaf crates have their own path-filtered workflow (ai-core, atomic, audio, crw, dialogs, doc, docpath, ecproj-format, font-store, i18n, jpeg, keymap, media, pcraft-format, pdf, print, proof, update, vectorcraft-format, web-api, web-host, window). What it does not cover: the domain crates that use the framework (color, imaging, draw, browse, text, pages, table, timeline, review, layers, menu, font-manager, automation), the gallery, the story renderer and the umbrella crate have no workflow, and nothing runs the full workspace build or test. A change in one of those crates is checked by its own `cl test` only. ## Profiles diff --git a/tools/cl b/tools/cl index ea29217fd..d4a1b3c44 100755 --- a/tools/cl +++ b/tools/cl @@ -15,12 +15,12 @@ Every cargo command runs through a job-pool launcher when it is on the PATH, else plain cargo. CARGO_TARGET_DIR defaults to -target when that directory exists beside the worktree. Why one feature set: cargo builds a crate once per distinct feature set, and everything above it again. The gallery -turns on craft-ui's `app`, the story renderer `snapshot`, the tests `testing` and the domain crates' `screen-testing`; -a command that leaves one of them off builds a second variant of the framework (minutes) and the dependants above it. -The canonical set for a crate is its own test feature (`screen-testing`, else `testing`) plus, for every crate that -depends on the framework, craft-ui's `app`, `testing` and `snapshot` (or craft-ui-contract's `testing` and `snapshot` -and craft-ui-shell's `app` for the framework crates themselves). Builds that take other features (CI's -`--all-features`, wasm checks) belong on GitHub. docs/development.md has the whole picture. +turns on craft-ui's `app`, the tests `testing` (which includes the snapshot renderer) and the domain crates' +`screen-testing`; a command that leaves one of them off builds a second variant of the framework (minutes) and the +dependants above it. The canonical set for a crate is its own test feature (`screen-testing`, else `testing`) plus, +for every crate that depends on the framework, craft-ui's `app` and `testing` (craft-ui-shell's `app` for the facade +and the shell). Builds that take other features (CI's `--all-features`, wasm checks) belong on GitHub. +docs/development.md has the whole picture. Guards: `--all-features`, `--bins` and workspace-wide builds are refused with the reason; after every command, a new feature variant of a framework crate in the target directory is named, with its feature set; `cl doctor` (also run @@ -36,19 +36,15 @@ import sys FRAMEWORK = ["craft-ui-contract", "craft-ui-widgets", "craft-ui-panels", "craft-ui-canvas", "craft-ui-patterns", "craft-ui-shell", "craft-ui"] ANCHORS = { - # package -> the features of its framework dependencies that every local build keeps on - "craft-ui": ["craft-ui-contract/snapshot", "craft-ui-shell/app"], - "craft-ui-shell": ["app", "craft-ui-contract/snapshot"], - "craft-ui-patterns": ["craft-ui-contract/snapshot"], - "craft-ui-canvas": ["craft-ui-contract/snapshot"], - "craft-ui-panels": ["craft-ui-contract/snapshot"], - "craft-ui-widgets": ["craft-ui-contract/snapshot"], - "craft-ui-contract": ["snapshot"], - "craft-ui-test-kit": ["craft-ui-contract/snapshot"], - "craft-ui-gallery": ["apps", "craft-ui/snapshot"], + # package -> the features of its framework dependencies that every local build keeps on. A feature can only be + # named for a direct dependency (`craft-ui-shell/app` from the facade, not `craft-ui-contract/...` from panels), so + # the runtime's test kit is one feature, `testing`, that every crate's own `testing` reaches. + "craft-ui": ["craft-ui-shell/app"], + "craft-ui-shell": ["app"], + "craft-ui-gallery": ["apps"], "story-render": [], } -FACADE_ANCHORS = ["craft-ui/app", "craft-ui/testing", "craft-ui/snapshot"] +FACADE_ANCHORS = ["craft-ui/app", "craft-ui/testing"] # Domain crates the story renderer can link, by the crate's short name. RENDER_FEATURES = { "automation", "browse", "color", "draw", "imaging", "layers", "menu", "pages", "print", "review", "table", "text", @@ -69,6 +65,8 @@ PINS = [ "craft-ui-macros must ask proc-macro2 for span-locations, or a build with design-lint in it changes the shared proc-macro2 and rebuilds the framework"), ("crates/ui-contract/Cargo.toml", r'^craft-window = \{[^\n]*features = \[[^\]]*"ui"', "craft-ui-contract must depend on craft-window with ui, or the shell's app flips craft-window under the whole framework"), + ("crates/ui-contract/Cargo.toml", r'^testing = \[[^\]]*"snapshot"', + "craft-ui-contract's testing must include snapshot, or crates above widgets cannot ask the runtime for the renderer and build a second variant"), ] @@ -129,6 +127,19 @@ def doctor(top, packages, quiet=False): if d["name"] == "egui" and d["kind"] == "dev" and d["features"]: problems.append(f"{manifest}: the egui dev-dependency asks for {d['features']}; a feature on a dev-dependency " "line changes egui under the framework between a crate's tests and its render") + # Every crate's canonical set must resolve: a plain feature of the crate, or `dep/feature` with `dep` a direct + # dependency (workspace members: a feature it defines), else cargo refuses the command. + for p in packages.values(): + direct = {d["name"]: d for d in p["dependencies"]} + for feature in canonical(packages, p["name"])[1]: + if "/" in feature: + dep, feat = feature.split("/", 1) + if dep not in direct: + problems.append(f"{p['name']}: canonical feature {feature} names {dep}, which is not a direct dependency") + elif dep in packages and feat not in packages[dep]["features"] and not any(d["name"] == feat and d["optional"] for d in packages[dep]["dependencies"]): + problems.append(f"{p['name']}: canonical feature {feature}: {dep} has no feature {feat}") + elif feature not in p["features"]: + problems.append(f"{p['name']}: canonical feature {feature} is not a feature of the crate") gallery = packages.get("craft-ui-gallery") if gallery: for d in gallery["dependencies"]: