gpui_kit/lib.rs
1//! GPUI Kit: one dependency for building desktop applications with GPUI.
2//!
3//! GPUI itself is published as a family of `gpui-pre-*` crates that move
4//! together. This crate depends on the matching set for you, so an
5//! application lists `gpui-kit` alone. `use gpui_kit::*;` is GPUI, and each
6//! layer is reachable by name:
7//!
8//! | Path | Crate | Feature |
9//! | --------------- | ----------------- | ---------------- |
10//! | `gpui_kit::*` | `gpui` | always |
11//! | `platform` | `gpui_platform` | desktop / web |
12//! | [`base`] | `gpui-base` | always |
13//! | [`component`] | `gpui-component` | `component` (on) |
14//! | [`assets`] | `gpui-kit-assets` | `assets` (on) |
15//!
16//! On desktop and web, `application` opens the platform. Mobile applications
17//! supply their backend to `Application::with_platform`. [`init`] initializes the enabled
18//! layers:
19//!
20//! ```no_run
21//! use gpui_kit::*;
22//!
23//! actions!(hello, [Quit]);
24//!
25//! struct Hello;
26//!
27//! impl Render for Hello {
28//! fn render(&mut self, _: &mut Window, _: &mut Context<Self>) -> impl IntoElement {
29//! div().child("Hello, World!")
30//! }
31//! }
32//!
33//! fn main() {
34//! gpui_kit::application().run(|cx| {
35//! gpui_kit::init(cx);
36//! gpui_kit::open_window(WindowOptions::default(), cx, |_, cx| cx.new(|_| Hello))
37//! .expect("failed to open window");
38//! });
39//! }
40//! ```
41//!
42//! Enable `gpui-fast` to select GPUI Fast for the core, platform, and enabled
43//! layers without changing imports. Upstream remains the default backend.
44//!
45//! See [`component`] for the same program with the styled component library.
46
47/// Defines unit actions without requiring consumers to depend on GPUI under the
48/// crate name `gpui`.
49///
50/// GPUI's original macro spells its derive as `gpui::Action`, which does not
51/// resolve when GPUI is consumed solely through this facade.
52#[macro_export]
53macro_rules! actions {
54 ($namespace:path, [ $( $(#[$attr:meta])* $name:ident),* $(,)? ]) => {
55 $(
56 #[derive(
57 ::std::clone::Clone,
58 ::std::cmp::PartialEq,
59 ::std::default::Default,
60 ::std::fmt::Debug,
61 $crate::Action
62 )]
63 #[action(namespace = $namespace)]
64 $(#[$attr])*
65 pub struct $name;
66 )*
67 };
68 ([ $( $(#[$attr:meta])* $name:ident),* $(,)? ]) => {
69 $(
70 #[derive(
71 ::std::clone::Clone,
72 ::std::cmp::PartialEq,
73 ::std::default::Default,
74 ::std::fmt::Debug,
75 $crate::Action
76 )]
77 $(#[$attr])*
78 pub struct $name;
79 )*
80 };
81}
82
83// Public facade decision — 2026-09-08:
84// GPUI Kit is the application-facing entry point. Users should depend on and
85// import gpui-kit without needing to know which GPUI crates implement it.
86// Keep GPUI APIs available through the Kit root and preserve the published
87// #[gpui_kit::test] macro. Do not replace it with Rust's built-in #[test].
88// A future switch to official GPUI crates is an internal dependency migration,
89// not a reason to steer Kit users toward gpui:: paths or require import changes.
90// Keep the existing gpui namespace re-export hidden for source compatibility;
91// it is not the recommended application API. It names this crate rather than
92// the GPUI crate: `gpui_kit::gpui::Window` is still GPUI's `Window` through the
93// glob below, and applications can alias the Kit as `gpui`
94// (`extern crate gpui_kit as gpui;`) so GPUI macro output resolves through the
95// Kit whichever GPUI it is built on. Pointing this at the GPUI crate would make
96// that alias ambiguous (E0659) wherever `gpui_kit::*` is glob-imported.
97//
98// With test-support, the glob below includes GPUI's test macro. Test modules
99// should import their Kit types explicitly to avoid shadowing Rust's #[test].
100#[cfg(not(feature = "gpui-fast"))]
101pub use ::gpui::*;
102#[cfg(feature = "gpui-fast")]
103pub use ::gpui_fast::*;
104
105// Preserve Kit-aware macro paths when the engine is Fast.
106#[cfg(all(feature = "gpui-fast", any(feature = "inspector", debug_assertions)))]
107pub use gpui_macros::derive_inspector_reflection;
108#[cfg(feature = "gpui-fast")]
109pub use gpui_macros::{
110 Action, AppContext, IntoElement, Render, VisualContext, bench, border_style_methods,
111 box_shadow_style_methods, cursor_style_methods, margin_style_methods, overflow_style_methods,
112 padding_style_methods, position_style_methods, property_test, register_action, style_helpers,
113 test, visibility_style_methods,
114};
115
116#[doc(hidden)]
117pub use crate as gpui;
118
119/// Whether this build selected GPUI Fast. Crates layered on the Kit that keep
120/// a backend feature of their own check it at compile time to stay in step.
121#[doc(hidden)]
122pub const GPUI_FAST: bool = cfg!(feature = "gpui-fast");
123
124/// UI integration testing: render real components in headless windows, dispatch
125/// pointer and keyboard events, and assert state, focus, layout and callbacks.
126/// Run tests with `#[gpui_kit::test]`; use this module to interact with their UI.
127#[cfg(feature = "test-support")]
128pub mod test;
129
130pub use ::gpui_base as base;
131#[cfg(all(
132 not(any(target_os = "ios", target_os = "android")),
133 feature = "gpui-fast"
134))]
135pub use ::gpui_fast_platform as platform;
136#[cfg(all(target_family = "wasm", feature = "gpui-fast"))]
137pub use ::gpui_fast_web as web;
138#[cfg(all(
139 not(any(target_os = "ios", target_os = "android")),
140 not(feature = "gpui-fast")
141))]
142pub use ::gpui_platform as platform;
143#[cfg(all(target_family = "wasm", not(feature = "gpui-fast")))]
144pub use ::gpui_web as web;
145pub use gpui_base::is_mobile;
146
147/// The styled component library.
148///
149/// ```no_run
150/// use gpui_kit::component::button::*;
151/// use gpui_kit::*;
152///
153/// struct Hello;
154///
155/// impl Render for Hello {
156/// fn render(&mut self, _: &mut Window, _: &mut Context<Self>) -> impl IntoElement {
157/// div().child(Button::new("ok").primary().label("Let's Go!"))
158/// }
159/// }
160///
161/// fn main() {
162/// gpui_kit::application().run(|cx| {
163/// gpui_kit::init(cx);
164/// gpui_kit::open_window(WindowOptions::default(), cx, |_, cx| cx.new(|_| Hello))
165/// .expect("failed to open window");
166/// });
167/// }
168/// ```
169#[cfg(feature = "component")]
170pub use ::gpui_component as component;
171
172#[cfg(feature = "assets")]
173pub use ::gpui_kit_assets as assets;
174
175/// Open a window with a Base Root and return the window and application content.
176/// Applications own quit/close actions and confirmation flows.
177/// Call [`init`] before opening application windows.
178/// The builder returns application content, not another Root.
179///
180/// In an async context, call this inside `cx.update`.
181pub fn open_window<V: Render>(
182 options: WindowOptions,
183 cx: &mut App,
184 build: impl FnOnce(&mut Window, &mut App) -> Entity<V>,
185) -> Result<(AnyWindowHandle, Entity<V>)> {
186 let mut built = None;
187 let window = cx.open_window(options, |window, cx| {
188 let view = build(window, cx);
189 built = Some(view.clone());
190 cx.new(|cx| base::Root::new(view, window, cx))
191 })?;
192 Ok((
193 window.into(),
194 built.expect("open_window ran its build closure"),
195 ))
196}
197
198// Mobile applications provide their platform with `Application::with_platform`.
199#[cfg(not(any(target_os = "ios", target_os = "android")))]
200pub use platform::application;
201
202/// Initializes every enabled layer. Call it once, before using anything else.
203///
204/// With the `component` feature (on by default) this is
205/// `gpui_component::init`, which also initializes `gpui-base`; otherwise it
206/// is `gpui_base::init`.
207pub fn init(cx: &mut App) {
208 #[cfg(feature = "component")]
209 gpui_component::init(cx);
210 #[cfg(not(feature = "component"))]
211 gpui_base::init(cx);
212}
213
214/// Fluent UI test observation, inert unless `test-support` is enabled.
215pub use gpui_base::TestSupportExt;