Initial GPUI Wayland terminal with Alacritty core
This commit is contained in:
@@ -0,0 +1,149 @@
|
||||
# Terminal
|
||||
|
||||
A small GPU-rendered terminal built with [GPUI 0.2.2](https://gpui.rs/) and
|
||||
[alacritty_terminal 0.26.0](https://docs.rs/alacritty_terminal/0.26.0/).
|
||||
The initial target is Linux desktop on Wayland. Alacritty provides the terminal
|
||||
state machine, VTE parser, scrollback, PTY, and shell I/O; GPUI provides the window,
|
||||
text rendering, and desktop input.
|
||||
|
||||
## Build and run
|
||||
|
||||
Use a recent stable Rust toolchain; development currently uses Rust 1.96. Launch
|
||||
from Linux 5.3 or newer (pidfd-based shell cleanup), in a running Wayland desktop with `WAYLAND_DISPLAY` set and a working Vulkan
|
||||
driver. This build enables GPUI's Wayland backend only.
|
||||
|
||||
Representative Fedora dependencies:
|
||||
|
||||
```sh
|
||||
sudo dnf install gcc gcc-c++ make cmake pkgconf-pkg-config \
|
||||
fontconfig-devel freetype-devel libxkbcommon-devel libxkbcommon-x11-devel \
|
||||
libxcb-devel wayland-devel openssl-devel vulkan-loader mesa-vulkan-drivers \
|
||||
dejavu-sans-mono-fonts
|
||||
```
|
||||
|
||||
Representative Ubuntu dependencies:
|
||||
|
||||
```sh
|
||||
sudo apt install build-essential cmake pkg-config \
|
||||
libfontconfig1-dev libfreetype6-dev libxkbcommon-dev libxkbcommon-x11-dev \
|
||||
libxcb1-dev libwayland-dev libssl-dev libvulkan1 mesa-vulkan-drivers \
|
||||
fonts-dejavu-core
|
||||
```
|
||||
|
||||
The package names follow the relevant portions of
|
||||
[Zed's Linux dependency script](https://github.com/zed-industries/zed/blob/main/script/linux).
|
||||
Your GPU may need its vendor's Vulkan driver instead of Mesa. GPUI 0.2.2 also
|
||||
links the XKB X11 library even when only its Wayland window backend is enabled.
|
||||
|
||||
```sh
|
||||
cargo run --locked
|
||||
# Optimized build:
|
||||
cargo run --locked --release
|
||||
```
|
||||
|
||||
The window starts `$SHELL`, falling back to `/bin/sh`, and inherits the launch
|
||||
directory. The child receives `TERM=xterm-256color` and `COLORTERM=truecolor`.
|
||||
Run `exit` or close the window to end the session. To select another shell:
|
||||
|
||||
```sh
|
||||
SHELL=/bin/bash cargo run --locked
|
||||
```
|
||||
|
||||
For diagnostics, use `RUST_LOG=debug cargo run --locked`. If no window appears,
|
||||
check that the process has access to your Wayland session and that Vulkan works
|
||||
on that desktop. To inspect the renderer's CPU work without enabling logs from
|
||||
all dependencies:
|
||||
|
||||
```sh
|
||||
RUST_LOG=terminal::timing=debug cargo run --locked
|
||||
```
|
||||
|
||||
Each frame logs `prepare_us` and `paint_us`, the time in microseconds spent in
|
||||
our preparation and painting callbacks. These exclude GPU execution, compositor
|
||||
scheduling, and presentation; they are not measurements of total input latency.
|
||||
|
||||
## Controls and behavior
|
||||
|
||||
| Input | Action |
|
||||
| --- | --- |
|
||||
| Drag with the left mouse button | Select text |
|
||||
| Double-click / triple-click | Select a word / line |
|
||||
| Ctrl+Shift+C | Copy the selection |
|
||||
| Ctrl+Shift+V | Paste, respecting bracketed-paste mode |
|
||||
| Mouse wheel / touchpad | Scroll terminal history |
|
||||
| Shift+PageUp / Shift+PageDown | Scroll one page |
|
||||
| Shift+Home / Shift+End | Jump to the oldest history / live screen |
|
||||
|
||||
Typing returns to the live screen. Ctrl+C, Ctrl+D, Alt combinations, arrows,
|
||||
navigation keys, and function keys are sent to the terminal application.
|
||||
In alternate-screen applications, Shift+navigation is passed through and the
|
||||
wheel sends arrow keys when the application enables alternate scrolling.
|
||||
|
||||
The renderer supports ANSI and 256-color palettes, truecolor, bold/italic/dim,
|
||||
underlining, reverse video, selection, wide characters and combining marks.
|
||||
Window resizing updates both the terminal grid and PTY size. Alternate-screen
|
||||
applications use Alacritty's terminal modes. Scrollback retains up to 10,000
|
||||
lines by default. The view selects an installed font in this order: Hermit
|
||||
(including its Hurmit Nerd Font variants), SF Mono, Noto Sans Mono, Iosevka,
|
||||
then another fixed-pitch family. Font advances are checked to avoid choosing a
|
||||
proportional fallback. Text is 15 logical pixels, with a 20-pixel line height and
|
||||
8-pixel padding.
|
||||
|
||||
## Structure
|
||||
|
||||
| Module | Responsibility |
|
||||
| --- | --- |
|
||||
| `src/main.rs` | Application startup and window lifecycle |
|
||||
| `src/session.rs` | One shell, PTY event loop, terminal grid, resize, and shutdown |
|
||||
| `src/terminal.rs` | One terminal view: focus, selection, scrollback, clipboard, text input, and render coordination |
|
||||
| `src/render.rs` | Cached terminal text layout and batched drawing |
|
||||
| `src/input.rs` | Xterm-style key encoding and paste framing |
|
||||
| `src/colors.rs` | Default palette, runtime color overrides, and cell color attributes |
|
||||
| `src/fonts.rs` | Preferred installed fonts and verified fixed-pitch fallback |
|
||||
|
||||
The session does not depend on GPUI or window layout. Future tabs or split panes
|
||||
can compose multiple views and sessions while reusing the parser and PTY code.
|
||||
Persistent multiplexing would add a session owner outside the window lifecycle.
|
||||
|
||||
PTY events wake the UI through an asynchronous channel. Output notifications
|
||||
are coalesced, and the UI yields between event batches so a busy child cannot
|
||||
monopolize the UI task. There is no periodic redraw polling. Typing requests a
|
||||
new frame when shell output arrives, or immediately if it changes selection,
|
||||
scrollback position, or input-method composition.
|
||||
|
||||
The renderer retains shaped text for unchanged rows. It groups adjacent ASCII
|
||||
cells into text runs, while keeping wide and combining-character cells aligned
|
||||
to terminal columns. Blank margins are skipped, and matching backgrounds and
|
||||
text decorations are merged into spans to reduce drawing work.
|
||||
|
||||
The build uses published crates and does not require a local Alacritty checkout.
|
||||
`vendor/xattr` carries a small compatibility patch for GPUI's transitive
|
||||
`zed-async-tar` dependency: Linux now uses `libc::ENODATA` in place of a removed
|
||||
`ENOATTR` alias. See [the patch notes](vendor/xattr/PATCH.md). The dependency
|
||||
versions are recorded in `Cargo.lock`.
|
||||
|
||||
## Development and scope
|
||||
|
||||
The development profile retains debug information and assertions, with level-1
|
||||
optimization and level-2 optimization for GPUI and the font-shaping crates.
|
||||
This keeps `cargo run` responsive during window resizing; the first build takes
|
||||
longer than a fully unoptimized build. Unicode clusters use cached glyphs in one
|
||||
shared paint layer, preserving cell positions without per-character layers.
|
||||
|
||||
```sh
|
||||
cargo fmt --check
|
||||
cargo check --locked
|
||||
cargo test --locked
|
||||
cargo clippy --locked --all-targets -- -D warnings
|
||||
```
|
||||
|
||||
Tests cover key and paste encoding, palette behavior, terminal parsing and
|
||||
resizing, and PTY lifecycle. They do not replace testing rendering and input
|
||||
under a real compositor.
|
||||
|
||||
This first version has a single shell and window. It does not yet provide panes,
|
||||
tabs, session persistence, configuration files, application mouse reporting,
|
||||
the Kitty keyboard protocol, OSC 52 clipboard access, or clickable hyperlinks.
|
||||
macOS is an intended next target and has not been validated. Font shaping,
|
||||
input methods, and terminal application compatibility still need broader
|
||||
desktop testing.
|
||||
Reference in New Issue
Block a user