70 lines
3.0 KiB
Markdown
70 lines
3.0 KiB
Markdown
# zterm
|
||
|
||
GPU-accelerated Wayland terminal emulator. Single Rust crate, edition 2024.
|
||
|
||
## Build & Run
|
||
|
||
```
|
||
cargo run # dev build, Wayland only
|
||
cargo build --release # release
|
||
cargo test # tests
|
||
```
|
||
|
||
## Features
|
||
|
||
| Feature | Effect |
|
||
|---------|--------|
|
||
| `webm` (default) | Enable WebM video via ffmpeg-next 8.x |
|
||
| `render_timing` | Enable per-frame parse/render timing instrumentation |
|
||
| `production` | `log/release_max_level_off` — zero logging overhead |
|
||
|
||
Disable webm: `--no-default-features --features render_timing`
|
||
|
||
## Architecture
|
||
|
||
- **Single process**: owns PTY, terminal state, rendering. No multi-process IPC.
|
||
- **Kitty-style shared parser** (`SharedParser` in `vt_parser.rs`): 1MB ring buffer. I/O thread writes directly into it; main thread parses in-place. Lock released during parsing so I/O continues.
|
||
- **Split tree** (`SplitNode` in `main.rs`): binary tree of panes. Layout computed via recursive `layout()` pass.
|
||
- **GPU rendering** (`renderer.rs`): wgpu + WGSL shaders. Instanced rendering with sprite atlas. Per-pane GPU buffers.
|
||
- **Kitty graphics protocol** (`graphics.rs`): PNG, GIF, WebM inline images.
|
||
|
||
## Key files
|
||
|
||
| File | Contents |
|
||
|------|----------|
|
||
| `src/main.rs` | `App` state machine, event loop, split tree, tab/pane management, keybindings |
|
||
| `src/terminal.rs` | Terminal grid, scrollback buffer, cursor, colors, cell attributes, `Handler` impl |
|
||
| `src/vt_parser.rs` | `SharedParser` (ring buffer + I/O), `Parser` (VT escape sequence parsing), `Handler` trait |
|
||
| `src/renderer.rs` | wgpu renderer, glyph atlas, font loading, instanced rendering pipeline |
|
||
| `src/graphics.rs` | Kitty graphics protocol parser (PNG/GIF/WebM) |
|
||
| `src/config.rs` | JSON config from `~/.config/zterm/config.json`, keybinding resolver |
|
||
| `src/pty.rs` | PTY master, fork/exec child shell, SIGWINCH resize |
|
||
| `src/pipeline.rs` | wgpu pipeline builder |
|
||
| `src/keyboard.rs` | Kitty keyboard protocol, key encoding |
|
||
| `zterm.terminfo` | Custom terminfo — install with `tic -x -o ~/.terminfo zterm.terminfo` |
|
||
| `src/bin/bench_process.rs` | Benchmark binary |
|
||
|
||
## Shaders
|
||
|
||
WGSL files: `src/glyph_shader.wgsl`, `src/image_shader.wgsl`, `src/quad_shader.wgsl`, `src/statusline_shader.wgsl`, `src/shader.wgsl` (edge glow).
|
||
|
||
## Config
|
||
|
||
`~/.config/zterm/config.json` — auto-created on first run. Fields: `font_family`, `font_size`, `tab_bar_position`, `background_opacity`, `scrollback_lines`, `inactive_pane_fade_ms`, `inactive_pane_dim`, `edge_glow_intensity`, `pass_keys_to_programs`, `keybindings`.
|
||
|
||
## Style
|
||
|
||
- `.rustfmt.toml`: `max_width = 80`
|
||
- `.gitignore` excludes `Cargo.lock` and `/benches` (unusual for Rust)
|
||
|
||
## Testing
|
||
|
||
Tests live inline in source files: `vt_parser.rs`, `simd_utf8.rs`, `graphics.rs`, `vt_test_osc.rs`. Run with `cargo test`.
|
||
|
||
## Setup
|
||
|
||
- **Wayland compositor** required (X11 not supported)
|
||
- **FFmpeg 5.x–8.x** system libraries (for `webm` feature)
|
||
- **terminfo**: install `zterm.terminfo` so shells know the terminal type
|
||
- **Nerd Font** recommended for statusline icons (folder, branch, etc.)
|