The crate map
Every crate in the workspace with its layer and publication status, the external dependencies, the ledger checks that keep the graph layered, feature flags, and how a release is made.
The workspace has 64 crates under crates/, plus the xtask gate runner. 53 of them are published
to crates.io at version 0.1.0; the other 11 are tooling or the experimental Linux console stack. An
application depends on zgui and usually nothing else (see
What an application depends on).
Layers
Every crate belongs to one of nine layers, from L0 (foundation) to L8 (product). The architecture overview describes what each layer holds. A crate may depend on crates in its own layer or a lower one, never on a crate in a higher layer.
Each manifest declares its layer in a comment above [dependencies]:
[package]
name = "zgui-layout"
version.workspace = true
edition.workspace = true
# ... the other shared package keys
# L4 — engines. Every dependency is inherited: `foo.workspace = true`.
[dependencies]
zgui-css = { path = "../zgui-css", version = "0.1.0" }
cephal.workspace = truecargo xtask new-crate <name> --layer L4 writes such a manifest and a crate root with
#![deny(missing_docs)] and #![forbid(unsafe_code)]. It accepts L0 to L8 only.
The rule keeps each part replaceable and testable on its own:
- A backend upgrade reaches one crate. A breaking winit release touches
zgui-platform-winitand nothing else. - Every stage is testable without the one below it. The style engine runs without layout, layout runs with fixed-metrics text and no fonts, paint runs without a GPU, and the frame loop runs without a display server.
- A second implementation is not a fork. There are four platform backends, two vector rasterisers, two text metric sources, and a capture renderer beside the real one.
When a dependency would point upward
A stage that needs a fact from a higher stage must be handed it. Use one of three moves:
- Invert the dependency. The lower crate declares a trait; the higher crate implements it and passes it in.
- Push the type down.
zgui-vocabexists for this. - Add a facade.
zgui-cssis the facade for the style engine.
A feature flag that enables an upward edge does not help: the layers check reads
normal and build dependencies, optional or not.
All crates
"Published" means the crate is on crates.io. Unpublished crates have publish = false in their
manifest.
| Crate | Layer | Published | Purpose |
|---|---|---|---|
zgui-geom | L0 | yes | Coordinate spaces and units (CssPx, DevicePx, Au) and plain geometry types. |
zgui-color | L0 | yes | CSS colour: fourteen colour spaces, conversion, and interpolation. |
zgui-arena | L0 | yes | Arena storage with stable addresses and typed handles. |
zgui-interned | L0 | yes | Interned strings, compared by pointer. |
zgui-bits | L0 | yes | Invalidation primitives: dirty flags and damage sets. |
zgui-profile | L0 | yes | Frame stages as tracing spans, work counters, and the latency trace. |
zgui-vocab | L1 | yes | Types shared by the view layer and the document: events, keys, modifiers, roles, states. |
zgui-css | L1 | yes | The computed-style facade. The one place the style engine's types are named for other crates. |
zgui-scene | L1 | yes | The renderer-independent display list. See Paint and the scene. |
zgui-render | L1 | yes | The Renderer and VectorRaster contracts. No implementation. See The renderer. |
zgui-atlas | L1 | yes | Texture-atlas placement, eviction, reference counts, and the upload queue. No GPU. |
zgui-platform | L1 | yes | The contract a windowing backend implements. See The platform layer. |
zgui-reactive | L1 | yes | Signals, memos, stores, owners, and the UI-thread executor. |
zgui-image | L1 | yes | Raster image decoding, decode limits, and registered in-memory image bytes. |
zgui-wgsl | L1 | yes | Shared WGSL building blocks and the rules that assemble built-in and application shader modules. |
zgui-render-wgpu | L2 | yes | The wgpu renderer: device, pipelines, batching, and the persistent target a frame is composed into. |
zgui-render-vector-vello | L2 | yes | Vector rasterisation on compute shaders, built on Vello. |
zgui-render-vector-coverage | L2 | yes | Vector rasterisation for devices without compute shaders. |
zgui-platform-wayland | L2 | yes | The native Wayland backend. Compiles to an empty crate off Linux and the BSDs. |
zgui-platform-winit | L2 | yes | The portable backend for X11, Windows, macOS, and Wayland on request. |
zgui-platform-headless | L2 | yes | A platform with no window system: a virtual clock, scripted input, recording surfaces. |
zgui-tokio | L2 | yes | Optional Tokio backend for background work and UI tasks. |
zgui-drm | L2 | no | Linux DRM/KMS: modes, planes, framebuffers, page flips. Console stack. |
zgui-evdev | L2 | no | Linux evdev input devices and events. Console stack. |
zgui-libinput | L2 | no | Input device configuration through libinput, loaded at run time. Console stack. |
zgui-xkb | L2 | no | Keyboard layouts through libxkbcommon, loaded at run time. Needs nightly. Console stack. |
zgui-seat | L2 | no | Session and device access through libseat, loaded at run time. Console stack. |
zgui-platform-drm | L2 | no | The platform backend for a bare Linux console. Console stack. |
zgui-dom | L3 | yes | The document: one arena of nodes, safe to read from many threads during the cascade. |
zgui-style | L4 | yes | The style engine, built on Stylo. |
zgui-layout | L4 | yes | The box tree and layout (block, flex, grid, inline), built on Cephal. |
zgui-text | L4 | yes | Text contracts, with no font engine behind them. |
zgui-text-style | L4 | yes | Text properties lowered from the cascade, split into shaping and non-shaping halves. |
zgui-text-parley | L4 | yes | The text engine: shaping, font resolution, metrics, glyph rasterisation, bidi. Built on Parley. |
zgui-paint | L4 | yes | Computed style and fragments into scene primitives. |
zgui-svg | L4 | yes | SVG documents read into outlines, paints and clips. |
zgui-canvas | L4 | yes | Retained shape lists that applications draw into. |
zgui-input | L5 | yes | Hit testing, interaction state, focus, and event dispatch. |
zgui-scroll | L5 | yes | Scroll offsets, chaining, overscroll and momentum. |
zgui-a11y | L5 | yes | The accessibility tree, published through AccessKit, and incoming actions. |
zgui-anim | L5 | yes | Transitions and keyframe animations. |
zgui-edit | L5 | yes | Text editing: caret, selection, undo, IME composition, platform text keys. |
zgui-view | L6 | yes | The view layer: views, components, children, and the seams they are written against. |
zgui-view-dom | L6 | yes | The view layer over a real document. |
zgui-view-macro | L6 | yes | view!, #[component], #[slot], variants!, css! and style!. |
zgui-shader-macro | L6 | yes | The shader! macro. Validates and compiles application WGSL at build time. |
zgui-elements | L6 | yes | The element vocabulary: sixteen names, each a typed builder. |
zgui-custom | L6 | yes | The custom-element trait and the registry that connects it to layout and paint. |
zgui-runtime | L7 | yes | The frame pipeline: dispatch, restyle, layout, paint, draw, and the window set. |
zgui | L7 | yes | The umbrella crate an application depends on. |
zgui-shader | L7 | yes | Application shader declarations, typed parameters, and paint integration. |
zgui-wgpu | L7 | yes | Surface elements that show textures from another wgpu renderer. |
zgui-testkit-view | L7 | yes | Component tests: a recording tree, a scripted host, synthesised input, a virtual clock. |
zgui-testkit-scene | L7 | yes | Frame tests without a GPU or font files: a capture renderer, fixed-metrics text, counters. |
zgui-conformance | L7 | no | The CSS property coverage report, backed by tests. |
zgui-ui | L8 | yes | The component library. |
zgui-ui-primitives | L8 | yes | Headless interaction behaviours the components are built from. |
zgui-ui-tokens | L8 | yes | Design tokens and themes as CSS custom properties. |
zgui-ui-icons | L8 | yes | A vector icon set drawn by the vector element. |
zgui-devtools | L8 | yes | The inspector: document, styles, layout, and frame statistics. |
zgui-bench | L8 | no | Benchmarks and reference workloads. |
zgui-examples | L8 | no | The example applications in examples/. |
zgui-console | L8 | no | RunDrm::run_drm, the entry point that runs an App on a Linux console. Console stack. |
probe | none | no | Build canary: links every pinned external engine together. |
xtask | none | no | The build, test, gate and release runner. Lives beside crates/. |
The console stack is experimental. It stays in the repository, is not published, and is not
reachable through zgui. Its entry point lives in zgui-console, which an application names
beside zgui. See the platform layer.
What an application depends on
An application names zgui. The examples package shows this: every example depends on zgui only.
There are three exceptions:
| Crate | When an application names it |
|---|---|
zgui-image | To register encoded image bytes from memory (ImageBytes). File paths need only zgui. |
zgui-devtools | To mount the inspector. zgui does not re-export it, so a release build does not link it by accident. |
zgui-console | To run on a Linux console with run_drm. Not published. |
Test crates name zgui-testkit-view, zgui-testkit-scene or zgui-platform-headless in
[dev-dependencies]. None of them is re-exported by zgui.
The component library follows the same rule: zgui-ui-tokens, zgui-ui-icons and
zgui-ui-primitives depend on zgui only, and zgui-ui depends on those three and zgui.
crates/zgui/src/lib.rs re-exports the lower crates under short names:
pub use crate::app::{App, app};
pub use crate::error::Error;
pub use zgui_view_macro::{component, css, slot, style, variants, view};
pub use zgui_elements::expansion;
pub use zgui_atlas as atlas;
pub use zgui_bits as bits;
pub use zgui_canvas as canvas;
pub use zgui_custom as custom;
pub use zgui_elements as elements;
pub mod desktop {
pub use zgui_platform::{AppMenu, MenuAction, MenuEntry, MenuId, MenuRole, Shortcut, Submenu};
pub use zgui_runtime::desktop::{AppHookGuard, on_exit, on_menu, on_reopen};
}
pub use zgui_geom as geom;
pub use zgui_platform as platform;
pub use zgui_reactive as reactive;
pub use zgui_reactive::task;
pub use zgui_render as render;
pub use zgui_runtime as runtime;
pub use zgui_scene as scene;
pub use zgui_shader as shader;
pub use zgui_text as text;
#[cfg(feature = "tokio")]
pub use zgui_tokio as tokio;
pub use zgui_view as view;
pub use zgui_vocab as vocab;
pub use zgui_wgpu as surface;zgui::expansion
view! expands to calls into zgui-view and zgui-elements. A macro cannot know what the caller
named those crates, so the expansion always goes through ::zgui::expansion::view::… and
::zgui::expansion::elements::…. That lets a crate that writes views depend on zgui alone.
A crate that writes views without zgui supplies the root itself:
extern crate zgui_elements as zgui;Replacing a backend
| Replace | Depend on | Implement | Install with |
|---|---|---|---|
| The renderer | zgui-render | Renderer | App::with_renderer, which takes a zgui_runtime::RendererFactory |
| The vector rasteriser | zgui-render, zgui-render-wgpu | VectorRaster, zgui_render_wgpu::VectorSource | WgpuRenderer::set_vector_factory_for, usually through zgui_render_vector_vello::attach |
| The platform | zgui-platform | PlatformCx, Surface, Clock, Waker, Clipboard | A driver FnOnce(Box<dyn AppHandler>) -> Result<(), PlatformError> passed to App::run_on |
| The text engine | zgui-text | FontSource, FontMetricsSource, ParagraphShaper, GlyphRaster | zgui_runtime::App::with_text_engine, with_metrics, with_glyph_raster |
- Renderer. A renderer with no vector rasteriser attached draws general vector items as empty space, with no error. See Vello and coverage rasterisers and, for a host that already owns a wgpu device, Adopting a host-opened device.
- Platform. A platform backend does not implement
AppHandler; it calls one.zgui_runtime::Runtimeis the implementation. See Drivers and backend selection. - Text engine. The umbrella
Appdoes not expose the three text factories. It installs them fromzgui::app::Fonts, so a face registered once serves every window. To replace the text engine, build withzgui_runtime::Appdirectly. See The text engine.
Feature flags
All feature flags are off by default.
| Crate | Feature | Effect |
|---|---|---|
zgui | tokio | Runs background work and UI tasks on a Tokio runtime (zgui::tokio). |
zgui | instrument | Forwards to zgui-view/instrument. |
zgui-view | instrument | Records which component produced each part of the document. zgui-devtools turns it on. |
zgui-view | stub-backend | zgui_view::stub: an in-memory tree and host for the crate's own tests and doc tests. |
zgui-profile | counters | Keeps frame counters in release builds. They are always on with debug assertions. zgui-testkit-scene enables it as a normal dependency feature. |
zgui-bits | loom | Builds the atomics from loom for model checking. Panics outside loom::model. |
zgui, zgui-layout, zgui-platform-wayland | wall-clock | Compiles the wall-clock budget test target, which the gate runs in release mode. |
zgui-examples | drm | Builds the tty example against zgui-console. |
External dependencies
Every external dependency is declared once in [workspace.dependencies] and inherited with
foo.workspace = true, so each version, feature set and default-features choice exists in one
place. cargo xtask ledger versions reports any member that spells its own version.
The table lists the crates that name each dependency outside development dependencies.
| Dependency | Version | Named by | Purpose |
|---|---|---|---|
stylo, stylo_dom, stylo_atoms, stylo_static_prefs, selectors, servo_arc, web_atoms, cssparser, app_units, euclid | stylo =0.19.0 | zgui-css, zgui-dom, zgui-style (each a subset) | The style engine: parsing, selector matching, the cascade. app_units and euclid appear in trait signatures the document implements. |
cephal | 0.1.0 (crates.io) | zgui-layout | Retained, incremental block, flex and grid layout. |
parley, fontique | 0.11 (resolves to 0.11.1) | zgui-text-parley | Paragraph shaping and font resolution. fontique is patched from vendor/fontique inside the workspace. |
skrifa, swash | 0.44.0, 0.2.10 | zgui-text-parley | Font metrics and glyph rasterisation. |
zeno | 0.3.3 | zgui-paint | Small vector coverage masks. |
wgpu | 29.0.4 | zgui-render-wgpu, both vector rasterisers | The graphics API. |
naga, bincode | 29.0.4, 1.3 | zgui-render-wgpu, zgui-shader-macro | Parse and validate WGSL at build time, serialise the result, load it in the renderer. |
vello | 0.9.0 | zgui-render-vector-vello | Compute-shader path rasterisation. |
usvg | 0.46.0 | zgui-svg | Parses SVG into paths, paints and clips. Text support is disabled. |
image | 0.25 | zgui-image | PNG, JPEG, WebP, and the first frame of GIF. |
winit, accesskit_winit, arboard | 0.30.13, 0.33.2, 3.6 | zgui-platform-winit | Portable event loop, windows, accessibility and clipboard. |
smithay-clipboard | 0.7 | zgui-platform-winit (Linux, BSD) | The Wayland clipboard on the portable backend. |
muda, objc2, block2, objc2-foundation, objc2-app-kit | 0.21.0, 0.6.x, 0.3.2 | zgui-platform-winit (macOS) | The application menu, reopen requests, title-bar buttons, key and scroll monitors. |
smithay-client-toolkit, wayland-client, wayland-backend, wayland-protocols, calloop, calloop-wayland-source | 0.20.0, 0.31.15, 0.3.16, 0.32.13, 0.14.4, 0.4.1 | zgui-platform-wayland | The native compositor connection, protocols, and event loop. |
accesskit_unix, zbus | 0.22.1, 5.18 | zgui-platform-wayland | Native Wayland accessibility and the settings portal. |
accesskit | 0.24.1 | zgui-vocab, zgui-platform, zgui-a11y, zgui-text, the four platform backends | The accessibility tree as plain data. |
raw-window-handle | 0.6.2 | zgui-platform and the Wayland, winit and DRM backends | Window handles for the graphics API, confined to the GpuSurface sub-trait. |
reactive_graph, reactive_stores, any_spawner, send_wrapper | =0.2.14, =0.4.3, =0.3.0, 0.6 | zgui-reactive | The reactive engine and the executor slot. |
futures (thread-pool) | 0.3 | zgui-reactive, zgui-render-wgpu | The default background pool. |
tokio | 1 | zgui-tokio | The optional runtime. |
kurbo, peniko | 0.13.1, 0.6.1 | zgui-scene, zgui-svg, zgui-canvas, both vector rasterisers; kurbo also zgui-elements, zgui-text, zgui-text-parley | Curves and paint descriptions as plain data. |
etagere | 0.3 | zgui-atlas | Shelf allocation inside an atlas. |
bytemuck | 1.25 | zgui-geom, zgui-scene, zgui-render-wgpu, zgui-render-vector-coverage | Plain-data structs as GPU buffer bytes. |
syn, quote, proc-macro2 | 2.0, 1.0, 1.0 | zgui-view-macro, zgui-shader-macro | The procedural macros. |
rayon | 1.12 | zgui-style, zgui-layout | Parallel selector matching and layout batches. |
ash | 0.38 | zgui-platform-drm | Vulkan images a display can scan out. Console stack. |
rustix | 1.1 | zgui-drm, zgui-evdev, zgui-platform-drm, zgui-platform-wayland | Kernel calls without libc; the monotonic clock. |
bindgen | 0.72 | zgui-drm, zgui-evdev (build) | Kernel uapi bindings generated from vendored headers. |
libloading | 0.8 | zgui-xkb, zgui-seat, zgui-libinput | Load libxkbcommon, libseat and libinput at run time. |
thiserror, tracing, bitflags, rustc-hash, smallvec, toml | many | Utilities. Not ledgered, because none is an engine. | |
proptest, criterion, trybuild, loom, tracing-subscriber, accesskit_consumer, wayland-protocols-wlr | tests and tools | Property tests, benchmarks, compile-fail tests, the concurrency model checker, test logging, reading published accessibility trees, virtual Wayland input. |
Pins that fail silently
cargo xtask ledger versions (xtask/src/ledger/check/versions.rs) enforces these, because a
wrong value produces wrong behaviour rather than a build error:
| Pin | Reason |
|---|---|
stylo, reactive_graph, reactive_stores, any_spawner pinned to an exact patch release | A drift to another release would otherwise go unnoticed. Moving a pin is a deliberate change. |
reactive_graph enables effects | Without it, the interface compiles and runs but never updates. |
reactive_graph does not enable nightly | The workspace's nightly toolchain must not switch it on. |
cephal has default-features = false and exactly block, flex, grid | parallel would add a second worker pool; zgui drives its own pool through Cephal's batching seam. Each algorithm is a formatting context the box tree dispatches to. |
wgpu is 29.x, one copy in Cargo.lock | Vello 0.9 links wgpu 29.0.4 and shares one device, queue and target texture with the renderer. |
ash has one copy in Cargo.lock | The console backend passes vk::Image to wgpu-hal; two copies would be two unrelated types. |
linebender_resource_handle has one copy | It makes the text engine's and the rasteriser's font-data types the same type. |
skrifa has at most two copies | The text engine and Vello are on different releases. |
Ledger checks
cargo xtask ledger runs thirteen checks. Any violation fails the gate. cargo xtask ledger <name>
runs one check, and cargo xtask ledger --self-test runs every check against a fixture with a
planted violation, to prove that the check can fail.
| Check | What it asserts |
|---|---|
engines | Each external engine is named only by the crates permitted to name it. |
unsafe | unsafe is forbidden outside an allowlist, and every unsafe impl Send/Sync has a // SAFETY: comment. |
attribution | Adapted code carries its licence header and a matching NOTICE row. |
versions | Exact version pins, one copy of wgpu, and feature sets that fail silently. |
pinned | Two crates have exact dependency lists, and no crate below the view layer names zgui-view. |
layers | Every dependency points at the crate's own layer or a lower one. |
ignored | No test is #[ignore]d. |
counters | Every frame counter is incremented somewhere, or listed as waiting for its stage. |
skips | Every counter of avoided work names its pair and has a non-vacuity test. |
clock | Every wall-clock assertion lives in a target the gate runs in release mode. |
mutation | A document is changed only through its batch API, never through the arena. |
inert | Every enum variant that code branches on is constructed somewhere. |
tag-syntax | No view, in code or docs, uses the old tag syntax. |
layers check
The check reads the # L<n> — header of every member manifest and compares each edge in
[dependencies] and [build-dependencies]. A member without a header fails, so a new crate cannot
skip the rule. probe and xtask are the only members with no layer.
Development dependencies are not checked. Several crates drive their own tests through a higher
layer, for example taking zgui-testkit-scene (L7) for golden-image comparisons. Test binaries are
not linked into a consumer's build, so these edges do not change the shipped graph.
pinned check
Two crates have exact dependency lists, because other backends are substituted underneath them:
| Crate | Normal dependencies, exactly |
|---|---|
zgui-view | zgui-geom, zgui-interned, zgui-reactive, zgui-vocab |
zgui-vocab | accesskit, zgui-geom, zgui-interned |
Neither crate may see stylo, stylo_dom, selectors, cephal, parley, wgpu, vello,
winit, zgui-dom, zgui-layout, zgui-style, zgui-render, zgui-scene or zgui-platform
in any section, including development dependencies.
No crate below the view layer may depend on zgui-view. The check lists thirteen such crates by
name: zgui-input, zgui-scroll, zgui-a11y, zgui-anim, zgui-edit, zgui-layout,
zgui-style, zgui-dom, zgui-text, zgui-paint, zgui-scene, zgui-render and
zgui-platform. Event dispatch is the usual temptation: the input layer decides which listeners an
event reaches, and the view layer calls them.
engines check
xtask/src/ledger/check/engines.rs lists, for each external engine, the crates that may name it.
Replacing or patching an engine is therefore a change to a known set of manifests.
External dependencies shows which crates name each engine today. Any
dependency whose name starts with gpui is rejected outright.
Lints and unsafe
[workspace.lints] denies missing_docs, unsafe_code and broken intra-doc links, and warns on
unreachable_pub, private intra-doc links, all of clippy, and undocumented unsafe blocks. Every
member sets [lints] workspace = true.
cargo xtask ledger unsafe requires #![forbid(unsafe_code)] in every crate root outside this
allowlist:
| Crate | Allowed unsafe for |
|---|---|
zgui-arena | Chunk initialisation that hands out address-stable references. |
zgui-dom | The cell discipline and the mutation cell. |
zgui-geom | Plain-old-data impls for types sent to the GPU. |
zgui-render-wgpu | Loading a pipeline cache from a blob; creating a device through wgpu-hal with requested Vulkan extensions. |
zgui-render-vector-vello | Creating a pipeline cache from a blob. |
zgui-platform-winit | The Wayland clipboard constructor; AppKit calls for the macOS menu, reopen request and title-bar buttons. |
zgui-platform-wayland | Borrowing the compositor's display and surface pointers as window handles. |
zgui-drm | ioctls, mapping dumb buffers, owning dma-buf descriptors. |
zgui-evdev | ioctls and reading event records from a byte buffer. |
zgui-xkb, zgui-seat, zgui-libinput | Loading the library at run time and calling into it. |
zgui-platform-drm | Reporting a surface's DRM handles; the Vulkan calls that create scanout images. |
Every hand-written unsafe impl Send or unsafe impl Sync needs a // SAFETY: comment directly
above it.
Publishing and releases
The published crates are on crates.io at 0.1.0, tagged v0.1.0. An application adds them with
cargo add zgui or:
[dependencies]
zgui = "0.1"Toolchains
- Published crates build on stable Rust 1.90 or later.
rust-version = "1.90"is set in[workspace.package]. The CI job "Check stable 1.90" runscargo +1.90.0 checkover every published crate. - The repository is developed on a pinned nightly (
rust-toolchain.toml, currentlynightly-2026-04-16). Miri needs nightly, and so doeszgui-xkbin the console stack. The console crates do not inheritrust-version.
Package contents
[workspace.package] include limits every package to src/, build/, build.rs, README.md,
LICENSE and NOTICE. Tests, fixtures and test fonts are not shipped. Each published crate has its
own README.
The repository patches fontique (the font collection under Parley) from vendor/fontique, so that
a font query keeps resolved families between paragraphs. [patch.crates-io] applies only inside
the workspace. A crates.io build uses the released fontique: the text is the same, but font
resolution is slower. An application can opt into the patched copy:
[patch.crates-io]
fontique = { git = "https://github.com/zortax/zgui", tag = "v0.1.0" }One version for all crates
Every member inherits version from [workspace.package], and all crates are released together.
zgui 0.1.0 therefore always sits on zgui-render 0.1.0, and there is no compatibility matrix
between the framework's own crates.
xtask/src/release/lockstep.rs checks that:
- every member writes
version.workspace = true; - every dependency of a published crate that has a
pathalso has a version requirement, whether it is an internal crate or an external one, and whether it is written in the member or inherited from the workspace; - no published crate depends on an unpublished member, including optional and target-specific dependencies.
The release gate
cargo xtask release runs three steps:
- Lockstep, as above.
- Packaging.
cargo package --workspace --locked, excluding unpublished members, then builds every published crate from its package. This catches files the package leaves out and builds that read outside their own directory. - Compatibility.
cargo semver-checks check-releaseagainst the newestv*tag that does not contain the checked commit. Before the first tag, it reports "no baseline" instead of passing.
cargo xtask ci runs the same gate but only packages the crates, without building them.
The release itself has two parts. The crates are published from a local checkout with
cargo publish --workspace. Pushing a vX.Y.Z tag runs .github/workflows/release.yml, which
checks that the tag is on main and matches the workspace version, runs the full CI workflow, and
creates the GitHub release with generated notes.
API stability rules
#[non_exhaustive]marks enums that are expected to grow without a breaking change: error enums, frame outcomes, host-hook answers, and platform enums. (A unit test inzgui-platformrejects any public enum there without it.) Enums that list the framework's own content, such asPrimitiveKind,BatchandFilterinzgui-scene, are exhaustive on purpose: adding a member must update every match in the tree.- Traits grow with default methods. A method added later has a default body, so existing
implementations keep compiling. Every method of
zgui_runtime::HostBindinghas one. #[doc(hidden)]hides items that exist only so one crate can reach another, such as the typestate markers behind required-prop errors. The macro-expansion roots stay visible.
Next
Architecture overview
The pipeline these crates implement, what each layer holds, and the seams between them.
The platform layer
The platform contract and the Wayland, winit, headless and console backends.
Measurements
The standing gates, and how to run cargo xtask perf yourself.
The component library
An L8 crate that uses only the public API.