From 170b2dbc96213d2fd910f0cdddf774bbb29322d1 Mon Sep 17 00:00:00 2001 From: Mikhail Pertsev Date: Tue, 9 Jun 2026 22:13:23 +0200 Subject: [PATCH] gpui: Document standalone app setup (#58766) Summary: - Document `gpui_platform::application()` as the entry point for standalone GPUI apps. - Add platform-specific `gpui_platform` feature guidance for macOS, Linux/FreeBSD, and Windows. - Use Git dependencies for the repository-based setup example. Self-Review Checklist: - [x] I've reviewed my own diff for quality, security, and reliability - [x] Unsafe blocks (if any) have justifying comments - [x] The content is consistent with the [UI/UX checklist](https://github.com/zed-industries/zed/blob/main/CONTRIBUTING.md#uiux-checklist) - [x] Tests cover the new/changed behavior - [x] Performance impact has been considered and is acceptable Release Notes: - N/A --------- Co-authored-by: Christopher Biscardi --- crates/gpui/README.md | 37 ++++++++++++++++++++++++++++++++++--- 1 file changed, 34 insertions(+), 3 deletions(-) diff --git a/crates/gpui/README.md b/crates/gpui/README.md index 6d4a37932ff..132e5ac1e9f 100644 --- a/crates/gpui/README.md +++ b/crates/gpui/README.md @@ -5,17 +5,48 @@ for Rust, designed to support a wide variety of applications. ## Getting Started -GPUI is still in active development as we work on the Zed code editor, and is still pre-1.0. There will often be breaking changes between versions. You'll also need to use the latest version of stable Rust and be on macOS or Linux. Add the following to your `Cargo.toml`: +GPUI is still in active development as we work on the Zed code editor, and is still pre-1.0. There will often be breaking changes between versions. You'll also need to use the latest version of stable Rust. Add `gpui`, and optionally `gpui_platform`, to your `Cargo.toml`: ```toml gpui = { version = "*" } +gpui_platform = { version = "*", features = ["font-kit", "wayland", "x11"] } ``` +Everything in a standalone GPUI app starts with an `Application`. You can create one with `gpui_platform::application()`, which picks the windowing and text backends for the host OS, and kick off your application by passing a callback to `Application::run()`. Inside this callback, you can create a new window with `App::open_window()` and register your first root view. + +```rust,no_run +use gpui::*; + +fn main() { + gpui_platform::application().run(|cx: &mut App| { + // .. + }); +} +``` + +### `gpui_platform` + +The features on `gpui_platform` are platform-specific, so the list above is a safe cross-platform default. If you build for a single platform, you can trim it: + +- **macOS** — Rendering uses Metal and is always available, but glyph rasterization needs `font-kit`. Without it, GPUI falls back to a placeholder text system that lays text out but renders no glyphs. + + ```toml + gpui_platform = { version = "*", features = ["font-kit"] } + ``` + +- **Linux / FreeBSD** — enable at least one windowing backend for desktop windows: `wayland`, `x11`, or both. These features also compile the renderer and text system, so no separate text feature is needed. + + ```toml + gpui_platform = { version = "*", features = ["wayland", "x11"] } + ``` + +- **Windows** — no features are required. Windowing uses Win32 and text uses DirectWrite. `font-kit` has no effect here. + +### Additional Topics + - [Ownership and data flow](_ownership_and_data_flow) - [Accessibility](_accessibility) -Everything in GPUI starts with an `Application`. You can create one with `Application::new()`, and kick off your application by passing a callback to `Application::run()`. Inside this callback, you can create a new window with `App::open_window()`, and register your first root view. See [gpui.rs](https://www.gpui.rs/) for a complete example. - ### Dependencies GPUI has various system dependencies that it needs in order to work.