150 lines
6.7 KiB
Markdown
150 lines
6.7 KiB
Markdown
# 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.
|