aboutsummaryrefslogtreecommitdiff
path: root/vendor/libghostty-vt/src/terminal/build_options.zig
diff options
context:
space:
mode:
authorCan Celik <ogulcancelik@gmail.com>2026-09-10 21:51:57 +0300
committerGitHub <noreply@github.com>2026-09-10 21:51:57 +0300
commit425c86179791cd32e2d4ce0ae7f269940b4b0663 (patch)
treee52c4383a6d69216cbe2a32638bf90841d7e2189 /vendor/libghostty-vt/src/terminal/build_options.zig
parent90e947a6e26e02f10ec7f1694c4eb5b78a86406b (diff)
chore: upgrade libghostty and preserve terminal behavior (#3906)
Diffstat (limited to 'vendor/libghostty-vt/src/terminal/build_options.zig')
-rw-r--r--vendor/libghostty-vt/src/terminal/build_options.zig271
1 files changed, 255 insertions, 16 deletions
diff --git a/vendor/libghostty-vt/src/terminal/build_options.zig b/vendor/libghostty-vt/src/terminal/build_options.zig
index 136e0f10..f16cbf42 100644
--- a/vendor/libghostty-vt/src/terminal/build_options.zig
+++ b/vendor/libghostty-vt/src/terminal/build_options.zig
@@ -36,9 +36,246 @@ pub const Options = struct {
/// Options.
c_abi: bool,
+ /// Optional feature gates, all enabled by default. See Features.
+ features: Features = .{},
+
/// The version of the application.
version: std.SemanticVersion,
+ /// Optional features for lib artifacts. Disabling a feature removes
+ /// its C API exports and any stream-integrated handling from the
+ /// build, primarily so size-conscious embedders (e.g. wasm) can trim
+ /// the binary. The Ghostty application itself always builds with
+ /// every feature enabled.
+ ///
+ /// Field names are the accepted tokens for `-Dvt-features`, which
+ /// acts like `-Dcpu`: comma-separated modifications applied on top
+ /// of the default (all enabled) set. `+feature` and `feature`
+ /// enable, `-feature` disables. The special name `all` refers to
+ /// every feature, so `-Dvt-features=-all,+render-state` builds only
+ /// the render state API. Hyphens in names are interchangeable with
+ /// underscores. Fields are emitted verbatim as bool options on the
+ /// `terminal_options` module.
+ pub const Features = packed struct {
+ /// Terminal state serialization: encode a full terminal (screen
+ /// contents, scrollback, cursor, styles, modes, etc.) to a
+ /// compact binary format and decode it back into a live
+ /// terminal. Used for session persistence, window restoration,
+ /// and moving terminal state between processes.
+ ///
+ /// C API: `ghostty_snapshot_*` and, together with
+ /// `grid_introspection`, `ghostty_tracked_grid_ref_snapshot`.
+ snapshot: bool = true,
+
+ /// Textual export of terminal contents as plain text, VT
+ /// (replayable escape sequences), or HTML, with optional extras
+ /// such as cursor position, palette, modes, and tabstops. Used
+ /// for copy-to-clipboard, dump-to-file, and debugging.
+ ///
+ /// C API: `ghostty_formatter_*` and, together with `selection`,
+ /// `ghostty_terminal_selection_format_*`.
+ formatter: bool = true,
+
+ /// Text selection: select word/line/output/all, selection
+ /// ordering, adjustment, and containment math, and the
+ /// click/drag gesture state machine (single/double/triple
+ /// click behaviors). Selections are expressed in grid
+ /// references, so enabling this also keeps the untracked grid
+ /// reference constructors even if `grid_introspection` is
+ /// disabled.
+ ///
+ /// C API: `ghostty_terminal_select_*`,
+ /// `ghostty_terminal_selection_*`, `ghostty_selection_gesture_*`.
+ selection: bool = true,
+
+ /// Terminal search: find matches for a string in the active
+ /// area and scrollback (ASCII case-insensitive), with results
+ /// that survive primary/alternate screen switches, resize, and
+ /// scrollback pruning, plus match selection with wrap-around
+ /// and viewport scrolling. Used to implement find bars.
+ ///
+ /// C API: `ghostty_search_*`.
+ search: bool = true,
+
+ /// The render state API: a coherent, update-in-place view of
+ /// the visible screen (rows, cells, styles, cursor, colors,
+ /// palette) designed to drive a renderer at frame rates. This
+ /// is the primary read path for embedders that draw the
+ /// terminal.
+ ///
+ /// C API: `ghostty_render_state_*`.
+ render_state: bool = true,
+
+ /// Encoding of host input events into the byte sequences a
+ /// terminal application expects: keyboard input (including the
+ /// Kitty keyboard protocol), mouse reporting, focus reporting,
+ /// and (bracketed) paste. Any interactive embedder needs this;
+ /// a read-only viewer does not.
+ ///
+ /// C API: `ghostty_key_event_*`, `ghostty_key_encoder_*`,
+ /// `ghostty_mouse_event_*`, `ghostty_mouse_encoder_*`,
+ /// `ghostty_focus_encode`, `ghostty_paste_*`.
+ input_encode: bool = true,
+
+ /// Color utilities: luminance, perceived luminance, and
+ /// contrast math (e.g. for minimum-contrast rendering), color
+ /// string parsing (`#rrggbb`, X11 color names, XParseColor
+ /// `rgb:`/`rgbi:` device specs), the default 256-color palette
+ /// and palette generation from configurable bases, and the X11
+ /// color name table itself.
+ ///
+ /// C API: `ghostty_color_*`.
+ color: bool = true,
+
+ /// Direct inspection of grid contents at a position via grid
+ /// references: cell and row data getters (codepoints,
+ /// graphemes, style, hyperlink URI, wrap state, ...) plus
+ /// tracked grid references that stay valid across terminal
+ /// updates. Used for hyperlink hover/open, accessibility, and
+ /// tests; deliberately not built for render loops (use
+ /// `render_state` for that).
+ ///
+ /// C API: `ghostty_grid_ref_*`, `ghostty_tracked_grid_ref_*`,
+ /// `ghostty_cell_get*`, `ghostty_row_get*`, and (shared with
+ /// `selection`) `ghostty_terminal_grid_ref` /
+ /// `ghostty_terminal_point_from_grid_ref`.
+ grid_introspection: bool = true,
+
+ /// The APC glyph protocol: a Ghostty extension that lets
+ /// terminal applications register custom font glyphs (glyf
+ /// outlines) for private-use-area codepoints. Embedders that
+ /// don't render registered glyphs can disable this; the
+ /// sequences are still consumed and safely ignored.
+ ///
+ /// No C API surface of its own; this gates the stream handling
+ /// and glossary storage.
+ glyph_protocol: bool = true,
+
+ /// The Kitty graphics protocol: APC command parsing, image
+ /// transmission and storage (PNG decoding via the sys
+ /// interface), and placement tracking, plus the read APIs a
+ /// renderer uses to draw placed images. Disabled sequences are
+ /// still consumed and safely ignored.
+ ///
+ /// This requires the ability to get timestamps from the OS, so
+ /// it is always disabled on freestanding targets (e.g.
+ /// wasm32-freestanding) regardless of this setting.
+ ///
+ /// C API: `ghostty_kitty_graphics_*`.
+ kitty_graphics: bool = true,
+
+ pub fn parse(list: []const u8) error{UnknownFeature}!Features {
+ // Modifications apply on top of the default set.
+ var result: Features = .{};
+
+ var it = std.mem.splitAny(u8, list, ", ");
+ while (it.next()) |raw| {
+ if (raw.len == 0) continue;
+
+ var name = raw;
+ var enable = true;
+ switch (name[0]) {
+ '+' => name = name[1..],
+ '-' => {
+ enable = false;
+ name = name[1..];
+ },
+ else => {},
+ }
+
+ // A dangling sign with no name is malformed.
+ if (name.len == 0) return error.UnknownFeature;
+
+ // The special name "all" refers to every feature.
+ if (std.mem.eql(u8, name, "all")) {
+ inline for (@typeInfo(Features).@"struct".fields) |field| {
+ @field(result, field.name) = enable;
+ }
+ continue;
+ }
+
+ var found = false;
+ inline for (@typeInfo(Features).@"struct".fields) |field| {
+ if (eqlName(name, field.name)) {
+ @field(result, field.name) = enable;
+ found = true;
+ }
+ }
+ if (!found) return error.UnknownFeature;
+ }
+
+ return result;
+ }
+
+ /// Feature name equality where '-' in the input matches '_' in
+ /// the field name.
+ fn eqlName(input: []const u8, name: []const u8) bool {
+ if (input.len != name.len) return false;
+ for (input, name) |a, b| {
+ const norm: u8 = if (a == '-') '_' else a;
+ if (norm != b) return false;
+ }
+ return true;
+ }
+
+ test "parse" {
+ const testing = std.testing;
+
+ const none: Features = @bitCast(
+ @as(@typeInfo(Features).@"struct".backing_integer.?, 0),
+ );
+
+ // Empty input keeps the defaults.
+ try testing.expectEqual(Features{}, try Features.parse(""));
+
+ // All three token forms, comma separated.
+ try testing.expectEqual(
+ Features{ .snapshot = false },
+ try Features.parse("-snapshot"),
+ );
+ try testing.expectEqual(
+ Features{ .snapshot = false, .formatter = false },
+ try Features.parse("-snapshot,+render_state,-formatter,color"),
+ );
+
+ // The special "all" name refers to every feature.
+ try testing.expectEqual(none, try Features.parse("-all"));
+ try testing.expectEqual(Features{}, try Features.parse("-all,+all"));
+ var render_only = none;
+ render_only.render_state = true;
+ try testing.expectEqual(
+ render_only,
+ try Features.parse("-all,+render-state"),
+ );
+
+ // Hyphens are interchangeable with underscores.
+ try testing.expectEqual(
+ Features{ .input_encode = false, .grid_introspection = false },
+ try Features.parse("-input-encode,-grid_introspection"),
+ );
+
+ // Later tokens win.
+ try testing.expectEqual(
+ Features{},
+ try Features.parse("-snapshot,+snapshot"),
+ );
+
+ // Unknown names and dangling signs are errors.
+ try testing.expectError(error.UnknownFeature, Features.parse("bogus"));
+ try testing.expectError(error.UnknownFeature, Features.parse("-snapshot,-"));
+ }
+ };
+
+ /// Whether the Kitty graphics feature is effectively enabled for
+ /// the given target. Kitty graphics requires the ability to get
+ /// timestamps and there is no way to do that on freestanding
+ /// targets, so it is always disabled there regardless of the
+ /// feature setting.
+ pub fn kittyGraphics(self: Options, target: std.Target) bool {
+ if (target.os.tag == .freestanding) return false;
+ return self.features.kitty_graphics;
+ }
+
/// Add the required build options for the terminal module.
///
/// The memory referenced by self is expected to stick around (it isn't
@@ -55,25 +292,23 @@ pub const Options = struct {
opts.addOption(bool, "simd", self.simd);
opts.addOption(bool, "slow_runtime_safety", self.slow_runtime_safety);
- // Kitty graphics is almost always true. This used to be conditional on
- // some other factors but we've since generalized the implementation
- // to support optional PNG decoding, OS capabilities like filesystems,
- // etc. So its safe to always enable it and just have the
- // implementation deal with unsupported features as needed.
- //
- // We disable it on wasm32-freestanding because we at the least
- // require the ability to get timestamps and there is no way to
- // do that with freestanding targets.
- const target = m.resolved_target.?.result;
- opts.addOption(
- bool,
- "kitty_graphics",
- !(target.cpu.arch == .wasm32 and target.os.tag == .freestanding),
- );
-
// These are synthesized based on other options.
opts.addOption(bool, "tmux_control_mode", self.oniguruma);
+ // Feature gates, emitted as flat bools (e.g. `options.snapshot`).
+ const target = m.resolved_target.?.result;
+ inline for (@typeInfo(Features).@"struct".fields) |field| {
+ var value = @field(self.features, field.name);
+
+ // Kitty graphics is force-disabled on some targets; see
+ // kittyGraphics for details.
+ if (comptime std.mem.eql(u8, field.name, "kitty_graphics")) {
+ value = self.kittyGraphics(target);
+ }
+
+ opts.addOption(bool, field.name, value);
+ }
+
// Version information.
opts.addOption(
[]const u8,
@@ -92,3 +327,7 @@ pub const Options = struct {
m.addOptions("terminal_options", opts);
}
};
+
+test {
+ _ = Options.Features;
+}