ghostty-rs/docs/rewrite/notes/compat-GC.md

compat-GC: GTK/libadwaita compat fallbacks, bench modes, helpgen, CLI Windows

Sub-notes: compat-GC-bench.md, compat-GC-helpgen.md, compat-GC-cli.md.

1. GTK / libadwaita compatibility (crates/ghostty-apprt-gtk)

Ghostty's own minimum (finding)

ZIG/src/build/SharedDeps.zig runs blueprint.zig over every entry of gresource.blueprints, which refuses to compile a <maj>.<min>/x.blp if the libadwaita headers are older than that version; the list contains 1.5/ files (window, tab, command palette, ...). So Ghostty 1.3.1 cannot be built against libadwaita < 1.5, and the Zig code calls gtk_css_provider_load_from_bytes (4.12) and gtk_im_context_activate_osk (4.14) unguarded. Ghostty's real minimum is therefore GTK 4.14 / libadwaita 1.5, which is what the crate already required; I verified this by compiling with gtk4 features v4_8/v4_10 (fails on load_from_bytes/activate_osk) and v4_14 (compiles). The only change to the requirement is dropping the unneeded gnome_44 feature. In Zig the fallbacks below are only reachable in a (hypothetical) build against older headers; they are ported with identical selection logic.

Version gating (gtk_version.rs, adw_version.rs)

Zig's atLeast = comptime header version AND runtime library version. Rust:

• cargo features are the "header version": adw_1_3 < adw_1_4 < adw_1_5 and gtk_4_16 (gtk/v4_16); all are default. BUILD_LEVEL / const fn comptime_at_least read them; at_least = comptime_at_least && runtime_at_least; runtime_at_least/runtime_until unchanged. COMPTIME_VERSION (pkg-config) is kept for +version output.
• Types that Zig selects at comptime are selected with cfg(feature = ...).
• Debug builds only: GHOSTTY_DEBUG_FAKE_GTK_VERSION / GHOSTTY_DEBUG_FAKE_ADW_VERSION (e.g. 1.4.0) override the runtime version answers (fake_version.rs; no Zig counterpart) so runtime branches can be exercised on new libraries.
• Root build.rs links the binary with -z lazy (Rust defaults to -z now) so symbols only used behind a runtime check (GTK 4.16 gtk_css_section_get_bytes) don't stop an older library from loading the program, like Zig's lazy binding.

Fallbacks ported

Zig	Rust
class/dialog.zig Parent = AlertDialog / MessageDialog, present/close	class/dialog.rs: DialogParent + present/close per cfg adw_1_5; macros dialog_subclass_wrapper!/impl_dialog_parent! give the three subclasses (close-confirmation, config-errors, clipboard) the right @extends chain and response override for both parents
clipboard_confirmation_dialog.zig can_remember, template 1.4 vs 1.0	cfg_attr template resource ui/1.4 (adw_1_4) vs ui/1.0; remember_choice child only with SwitchRow; CAN_REMEMBER; remember=false without it
debug_warning.zig Parent adw.Bin/gtk.Box, template 1.3/1.2	class/debug_warning.rs cfg adw_1_3
surface_child_exited.zig Banner / SurfaceChildExitedNoop	class/surface_child_exited.rs: noop widget (no template, NOOP, close-request emitted from set_child_exited); Surface::child_exited returns false for the noop, as in Zig. NB: Zig has no 1.2/surface-child-exited.blp (the task text assumed one); the pre-Banner implementation is the Noop
window.zig actionAbout	adw::AboutDialog if supports_dialogs() else gtk::show_about_dialog
application.zig signalCssParsingError (GTK >= 4.16 branch)	css.rs: domain code message + \n<source bytes> (CssSection::bytes) behind gtk_4_16 + runtime check, plain line otherwise; tested via parsing_error_message
blueprint variants	build.rs already compiles 1.0/1.2/1.3/1.4/1.5 variants (same list as gresource.zig) into the gresource; the class selects at build level (as Zig)

Verification

• cargo clippy -p ghostty-apprt-gtk --all-targets -D warnings clean with default features AND with default = [] (temporarily edited), i.e. both the new and the fallback code compile.
• Default build: GTK app runs with the debug replay hook (paste dialog shows GhosttyClipboardConfirmationDialog with the remember switch; no GTK criticals).
• Fallback build (default = [], run via the replay hook): the paste confirmation and the close confirmation come up as adw::MessageDialog-based GhosttyClipboardConfirmationDialog / GhosttyCloseConfirmationDialog (transient for the window), the binary has no BIND_NOW.
• Workspace gate (excluding L1's in-progress ghostty-lib): cargo clippy --workspace --all-targets -D warnings, cargo test --workspace, cargo +nightly fmt --all pass. +help, +list-actions [--docs], +list-keybinds --help, +show-config --help are byte-identical to /usr/bin/ghostty.

Deviation found by the runtime check

Zig's GhosttyCloseConfirmationDialog registers a close-request signal; with the MessageDialog (a GtkWindow) parent that name already exists in the class ancestry and GObject aborts. Zig's fallback has the same latent bug (dead code upstream). The fallback build here names it dialog-close-request (close_confirmation_dialog.rs::CLOSE_REQUEST); default build unchanged.

Not testable here

Real old libraries (GTK < 4.16 / libadwaita < 1.5) are not installed; only the compile-time fallback selection and the version arithmetic are exercised.

2-4

See the sub-notes. Deviations vs the task text: Zig CodepointWidth has no uucode mode (bench); Zig does no file locking on Windows, so the faithful port is a no-op there (cli).