GPUI Box

GPUI Box is an independent distribution of GPUI: a hybrid immediate- and retained-mode, GPU-accelerated UI framework for Rust. It is derived from GPUI but maintained and released independently of Zed. GPUI Box is not an official Zed project.

The framework is pre-1.0 and may make breaking changes between releases. Version 0.1.0 requires Rust 1.97 or newer.

Getting Started

Use package aliases so application code keeps the familiar gpui and gpui_platform crate names:

[dependencies]
gpui = { package = "gpui-box", version = "0.1.0" }
gpui_platform = { package = "gpui-box-platform", version = "0.1.0", features = ["font-kit", "wayland", "x11"] }

gpui-box and the gpui-box-* platform crates are released as one compatible framework. Do not mix them with another GPUI distribution: Rust treats types from separate GPUI packages as distinct, even when their names and source APIs look alike. Using this package family throughout your dependency graph keeps a single GPUI type universe and avoids incompatible App, Window, and element types. Applications do not need a Zed checkout or a Git dependency.

Everything in a standalone GPUI Box application starts with an Application. gpui_platform::application() selects the windowing and text backends for the host OS. Pass a callback to Application::run(), then open a window with App::open_window() and register a root view.

use gpui::*;

fn main() {
    gpui_platform::application().run(|cx: &mut App| {
        // Open your first window here.
    });
}

Platform features

The gpui-box-platform features are platform-specific. The feature set above is a safe default for a project that targets all supported desktop platforms. Single-platform applications can trim it:

macOS — rendering uses Metal. Enable font-kit for glyph rasterization; without it, the fallback text system lays text out but renders no glyphs.
```
gpui_platform = { package = "gpui-box-platform", version = "0.1.0", features = ["font-kit"] }
```

Linux / FreeBSD — enable wayland, x11, or both. These features also enable the renderer and text system.

gpui_platform = { package = "gpui-box-platform", version = "0.1.0", features = ["wayland", "x11"] }

Windows — no gpui-box-platform features are required. Windowing uses Win32 and text uses DirectWrite; font-kit has no effect.

System dependencies

macOS

GPUI Box uses Metal. Install Xcode from the Mac App Store or the Apple Developer site, launch it once to install the macOS components, and install its command-line tools:

xcode-select --install
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer

The Big Picture

GPUI provides three levels of API:

Entities manage application state and communication. GPUI owns entities, which are accessed through owned smart pointers and framework contexts.
Views provide high-level declarative UI. A view is an Entity that implements Render; each frame it builds and styles an element tree.
Elements provide low-level imperative layout and painting for custom or performance-sensitive UI such as large virtualized lists.

The framework also provides user-defined actions and key bindings, platform services, an async executor integrated with the event loop, and #[gpui::test] with TestAppContext for UI tests.