# gpui-libghostty
Native Ghostty terminal and embedded Neovim components for GPUI.
## Status
Project status is alpha, expect bugs and instability.
## Crates
- `gpui-libghostty` hosts a command in Ghostty's native Metal renderer on
macOS or its OpenGL renderer in a native Wayland subsurface on Linux, and
forwards GPUI keyboard, key-repeat, mouse, scroll, focus, resize, and
visibility events.
- `gpui-neovim` starts Neovim with a private RPC socket and opens later files in
the same editor instance.
The native renderer supports macOS and Wayland. Linux uses a caller-owned EGL
OpenGL 4.3 context and does not depend on Ghostty's GTK application runtime or
copy frames through CPU memory. Fractional scaling uses `wp_viewporter` when
available and falls back to an integer Wayland buffer scale. X11 is
intentionally unsupported. Ghostty is
pinned to commit
`9f0e1719dc918368367d368bfe300f59bb68b5a4`; the required, pruned source closure
is under `crates/gpui-ghostty/vendor/ghostty` so Cargo and Crane include it
with the package.
## Requirements
- macOS and Xcode command-line tools, or Wayland with EGL, libc++, and desktop OpenGL 4.3
- Zig 0.16
- Neovim for `gpui-neovim`
Set `ZIG` to select a non-default Zig executable. Set `GPUI_NVIM` or assign
`NvimOptions::executable` to select Neovim.
## Native build cache
The first build compiles Ghostty with Zig. Later builds reuse the native archive
across Cargo workspaces. The default cache is
`$XDG_CACHE_HOME/gpui-libghostty`, `$HOME/Library/Caches/gpui-libghostty` on
macOS, or `$HOME/.cache/gpui-libghostty` on other systems. If the shared cache
cannot be created, the build falls back to the current Cargo target directory.
Set `GHOSTTY_NATIVE_CACHE_DIR`, `GHOSTTY_ZIG_PACKAGE_CACHE_DIR`, or
`GHOSTTY_ZIG_GLOBAL_CACHE_DIR` to absolute paths to override each cache. The
native cache key includes the Ghostty source, target, Zig version, SDK, and
build options, so a changed input gets a new archive.
## Terminal
```toml
[dependencies]
gpui-ghostty = { package = "gpui-libghostty", version = "0.1" }
```
```rust,ignore
use gpui_ghostty::{Terminal, TerminalOptions};
let terminal = Terminal::spawn(
TerminalOptions::new("bash", project_directory),
window,
cx,
)?;
```
`Terminal::spawn` returns `Entity<Terminal>`, which can be rendered directly as
a GPUI child.
## Neovim
```rust,ignore
use gpui_neovim::{NvimEditor, NvimOptions};
let editor = NvimEditor::spawn(
NvimOptions::new(project_directory, initial_file),
window,
cx,
)?;