From 63216eda8ecafc09e96daba0ad4cff80bbbf3c2a Mon Sep 17 00:00:00 2001 From: ddidderr Date: Mon, 12 Oct 2026 04:40:52 +0200 Subject: [PATCH] docs: add README, changelog entry and top-down architecture overview README explains what the rewrite covers, how to build, run, install and test it. ARCHITECTURE.md gains a top-down decomposition tree (binary -> runtime/core -> termio/terminal/renderer -> leaf crates) and an updated crate map with the actual internal dependencies, including the crates added during integration (apprt, inspector, onig, bench, build-data). CHANGELOG records the rewrite under Unreleased; no version bump. --- CHANGELOG.md | 19 +++++++++++ README.md | 65 +++++++++++++++++++++++++++++++++++ docs/rewrite/ARCHITECTURE.md | 66 +++++++++++++++++++++++++++--------- 3 files changed, 134 insertions(+), 16 deletions(-) create mode 100644 README.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 62517c1..4d737ca 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,3 +5,22 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +### Added + +- Complete Rust rewrite of Ghostty 1.3.1 for Linux: VT parser and stream, + terminal core (page list, screen, terminal, selection, formatter, search, + kitty graphics, tmux control mode), font engine (fontconfig, freetype, + harfbuzz, sprite font), OpenGL renderer with custom shader support, + termio (pty, child process, shell integration, terminfo), configuration + system with all options and docs, input and keybindings, core App/Surface, + GTK4/libadwaita app runtime, terminal inspector, and all `ghostty +action` + CLI commands. +- Bundled resources: shell integration, 463 themes, compiled terminfo, + desktop integration files, translations. +- `ghostty-bench` (benchmarks) and `ghostty-build-data` (shell completions, + Vim/Sublime/bat syntax, man pages). +- About 3000 tests, including all ported Zig tests and headless end-to-end + tests of the core with a real pty. diff --git a/README.md b/README.md new file mode 100644 index 0000000..6a453fd --- /dev/null +++ b/README.md @@ -0,0 +1,65 @@ +# ghostty-rs + +A Rust rewrite of the [Ghostty](https://ghostty.org) 1.3.1 terminal emulator +for Linux (GTK4 + libadwaita, OpenGL). + +It aims for behavioural parity with Ghostty: the same configuration file +format, options, defaults and documentation; the same keybindings and +actions; the same `ghostty +action` CLI; the same terminal emulation +(including kitty keyboard/graphics protocols, OSC 8 hyperlinks, semantic +prompts, synchronized output, tmux control mode); the same shell +integration, themes and terminfo. + +Out of scope: macOS, Windows, WASM, the embedded `libghostty` C API, and +Sentry crash reporting (disabled by default on Linux upstream). + +## Building and running + +Requirements: Rust (edition 2024), GTK ≥ 4.14, libadwaita ≥ 1.5, +fontconfig, freetype, harfbuzz, Oniguruma, libepoxy, `blueprint-compiler` +and `glib-compile-resources` at build time. + +```sh +cargo run # open a terminal window running your shell +cargo run -- -e htop # run a command +cargo run -- +list-themes # CLI actions work like Ghostty's +cargo run --profile production # optimized build (LTO, no debug assertions) +``` + +Development builds find `resources/` (shell integration, themes, terminfo) +automatically. Your existing Ghostty config +(`~/.config/ghostty/config[.ghostty]`) is used as-is. + +## Installing + +```sh +just install /usr/local # binary, share/ghostty, terminfo, desktop files, + # completions, man pages, translations, icons +just install /usr false true # system-package layout (lib/systemd/user) +``` + +## Testing + +```sh +just test # cargo test --workspace (~3000 tests) +just clippy # clippy with -D warnings +``` + +Every Zig `test` block of the ported files was ported to a Rust test. +`crates/ghostty-core/tests` holds end-to-end tests that drive the real core, +terminal and a real pty through a fake app runtime. `ghostty-bench` mirrors +Ghostty's benchmark tool; terminal stream throughput is on par with the Zig +build (see `docs/rewrite/notes/perf-P1.md`). + +## Documentation + +- `docs/rewrite/ARCHITECTURE.md` – top-down decomposition, crate map, key + design decisions, intentional omissions +- `docs/rewrite/STATUS.md` – work package history +- `docs/rewrite/notes/` – per-crate porting notes, deviations from Zig, + audits and verification reports + +## License + +MIT, like Ghostty. Bundled fonts and themes carry their own licenses (see +`crates/ghostty-font/res/` and `resources/themes/`). diff --git a/docs/rewrite/ARCHITECTURE.md b/docs/rewrite/ARCHITECTURE.md index 11c3844..afe00d5 100644 --- a/docs/rewrite/ARCHITECTURE.md +++ b/docs/rewrite/ARCHITECTURE.md @@ -6,26 +6,60 @@ to below as `ZIG/` (= `../../../ghostty`). Target platform: **Linux (GTK4 + libadwaita, OpenGL)**. macOS/Metal/CoreText, WASM, Windows and the embedded C API (`libghostty`) are out of scope. +## Top-down decomposition + +``` +ghostty (bin, src/main.rs) CLI `+action` dispatch or GTK app startup +├── ghostty-cli `ghostty +action` commands +├── ghostty-apprt-gtk GTK4/libadwaita runtime: windows, tabs, splits, +│ │ dialogs, GLArea surfaces, IPC, inspector windows +│ └── ghostty-apprt core<->runtime contract (actions, messages, traits) +└── ghostty-core App + Surface: input routing, bindings, mouse, + │ clipboard, config reload, per-surface threads + ├── ghostty-termio IO thread, pty, child process, stream handler + │ └── ghostty-terminal terminal state machine + │ ├── Terminal / Screen cursor, modes, scrolling, alt screen, selection + │ ├── PageList / Page scrollback memory model (slab nodes, tracked pins) + │ ├── render / formatter per-frame RenderState, text/VT/HTML export + │ ├── kitty / search / tmux kitty graphics, search thread, tmux control mode + │ └── ghostty-vt byte stream -> Parser -> Stream -> Handler actions + ├── ghostty-renderer OpenGL renderer (glow), renderer thread, shaders + │ └── ghostty-font fontconfig/freetype/harfbuzz, sprite font, atlas + ├── ghostty-inspector Dear ImGui terminal inspector + └── ghostty-config config file/CLI parsing, themes, keybinds + ├── ghostty-input keys, key encoding, binding sets, mouse + └── ghostty-os XDG, env, shell, locale, resources dir, flatpak +Support: ghostty-unicode (width/grapheme/case-fold tables), ghostty-datastruct +(split tree, LRU, queues), ghostty-onig (Oniguruma retry-limit FFI), +ghostty-bench (benchmarks), ghostty-build-data (completions, man pages, syntax). +``` + ## Crate map (workspace `crates/`) -| Crate | Ports (ZIG/src/...) | Depends on | +| Crate | Ports (ZIG/src/...) | Internal deps | |---|---|---| -| `ghostty-vt` | terminal/Parser, parse_table, UTF8Decoder, osc.zig + osc/*, csi, dcs, apc, sgr, color, x11_color, charsets, modes, ansi, device_status, mouse_shape, kitty/key, kitty/color, kitty/graphics_command, stream.zig | – | -| `ghostty-unicode` | unicode/* (width, grapheme break, props) | – | +| `ghostty-vt` | terminal/Parser, parse_table, UTF8Decoder, osc.zig + osc/*, csi, dcs, apc, sgr, color, x11_color, charsets, modes, ansi, device_status, mouse_shape, kitty/{key,color,graphics_command}, tmux/control, stream.zig, simd (scalar) | – | +| `ghostty-unicode` | unicode/* (width, grapheme break, props, symbols) + case folding, generated from vendored UCD 17.0.0 | – | | `ghostty-datastruct` | datastruct/* (split_tree, lru, circ_buf, blocking_queue, cache_table, ...) | – | -| `ghostty-os` | os/* (xdg, homedir, shell, locale, passwd, env, open, desktop, resourcesdir, hostname, TempDir, uri, ...) | – | -| `ghostty-input` | input/* (key, key_mods, keycodes, function_keys, key_encode, Binding, command, mouse, paste, kitty, Link) | vt | -| `ghostty-config` | config/*, cli/args.zig, cli/CommaSplitter.zig, cli/diagnostics.zig | input, os, vt | -| `ghostty-terminal` | terminal/ page, PageList, Screen, ScreenSet, Terminal, style, hyperlink, Tabstops, size, point, Selection, formatter, render, highlight, search/*, kitty/graphics_{image,storage,exec,unicode,render}, tmux/*, stream_readonly, StringMap, ref_counted_set, bitmap_allocator semantics | vt, unicode, datastruct | -| `ghostty-font` | font/* (Metrics, sprite/*, Atlas, discovery via fontconfig, face via freetype, shaper via harfbuzz, Collection, CodepointResolver, SharedGrid(Set), opentype/*, nerd_font_attributes) | config, unicode, terminal | -| `ghostty-renderer` | renderer/ generic, OpenGL (+ opengl/*), cell, cursor, image, link, size, State, Thread, Overlay, shadertoy, row, shaders/glsl | config, font, terminal | -| `ghostty-termio` | termio/*, pty.zig, Command.zig, shell-integration resources | config, terminal, os | -| `ghostty-cli` | cli/* actions (+list-themes, +show-config, +list-keybinds, ...) | config, input, os, font | -| `ghostty-inspector` | inspector/* (Dear ImGui terminal inspector: widgets, key + VT event recording) | input, renderer, terminal, vt, font, `dear-imgui-rs` | -| `ghostty-core` | App.zig, Surface.zig, surface_mouse.zig, apprt/action.zig, apprt/structs.zig, apprt/surface.zig, global.zig | everything below | -| `ghostty-apprt` | apprt/action.zig, structs.zig, surface.zig, ipc.zig (core↔runtime contract types) | vt, input, config, datastruct | -| `ghostty-apprt-gtk` | apprt/gtk/* | core, config, input | -| root `ghostty-rs` (bin `ghostty`) | main_ghostty.zig, build_config.zig | core, config, apprt-gtk | +| `ghostty-onig` | (Oniguruma whole-search retry limit used by StringMap.zig) | – | +| `ghostty-os` | os/* (xdg, homedir, shell, locale, passwd, env, open, desktop, resourcesdir, hostname, TempDir, uri, flatpak, systemd, cgroup, ...) | vt | +| `ghostty-input` | input/* (key, key_mods, keycodes, function_keys, key_encode, Binding, command, mouse, paste, kitty, Link) | vt, unicode | +| `ghostty-terminal` | terminal/ page, PageList, Screen, ScreenSet, Terminal, style, hyperlink, Tabstops, size, point, Selection, formatter, render, highlight, search/*, kitty/graphics_*, tmux/{layout,output,viewer}, stream_readonly, StringMap, ref_counted_set | vt, unicode, datastruct, onig | +| `ghostty-config` | config/*, cli/args.zig, cli/CommaSplitter.zig, cli/diagnostics.zig | input, os, terminal, vt | +| `ghostty-font` | font/* (Metrics, sprite/*, Atlas, discovery (fontconfig), face (freetype), shaper (harfbuzz) + run, Collection, CodepointResolver, SharedGrid(Set), opentype/*, nerd_font_attributes) | config, terminal, unicode, datastruct | +| `ghostty-renderer` | renderer/ generic, OpenGL + opengl/*, cell, cursor, image, link, size, State, Thread, Overlay, shadertoy, row, shaders/glsl | config, font, terminal, input, unicode, vt, datastruct | +| `ghostty-inspector` | inspector/* (Dear ImGui terminal inspector) | font, input, renderer, terminal, vt | +| `ghostty-apprt` | apprt/action.zig, structs.zig, surface.zig, ipc.zig, runtime traits | config, input, inspector, renderer, terminal, vt, datastruct | +| `ghostty-termio` | termio/*, pty.zig, Command.zig, terminfo/*, shell integration | apprt, config, os, renderer, terminal, vt, datastruct | +| `ghostty-core` | App.zig, Surface.zig, surface_mouse.zig, global.zig | apprt, config, font, input, inspector, os, renderer, terminal, termio, ... | +| `ghostty-cli` | cli/* actions, build_config.zig (build info) | apprt, config, font, input, os, vt | +| `ghostty-apprt-gtk` | apprt/gtk/* (+ ui/*.blp, css) | apprt, config, input, inspector, os, vt, datastruct | +| `ghostty-bench` | benchmark/*, synthetic/* | terminal, unicode, vt | +| `ghostty-build-data` | main_build_data.zig, extra/*, build/mdgen | cli, config, input, os, termio | +| root `ghostty-rs` (bin `ghostty`) | main_ghostty.zig | apprt, apprt-gtk, cli, config, core, os | + +Non-code: `resources/` (shell-integration, themes, terminfo), `dist/` (desktop +integration), `po/` (translations), crate-local `res/`/`shaders/`/`resources/`. ## Key design decisions