The README hasn't been updated in years basically!
This updates the README to make libghostty a first class citizen of the
project and to update our roadmap and goals for the project to more
accurately reflect our current state and future plans.
Fixes#11705
Add bg_color and fg_color options to GhosttyRenderStateRowCellsData that
resolve the final RGB color for a cell, flattening the multiple possible
sources. For background, this handles content-tag bg_color_rgb,
content-tag bg_color_palette (looked up in the palette), and the style
bg_color. For foreground, this resolves palette indices through the
palette; bold color handling is not applied and is left to the caller.
Both return GHOSTTY_INVALID_VALUE when no explicit color is set, in
which case the caller should fall back to whatever default color it
wants (e.g. the terminal background/foreground).
Fixes#11704
The RenderState empty initializer set both background and foreground to
the default RGB value of black (0, 0, 0), making text unreadable when a
caller has not explicitly configured terminal colors via DynamicRGB.
This is the common case for libghostty consumers.
Default the foreground to white so that the initial render state
provides readable white-on-black text out of the box.
Long term we also need to expose setting the default colors for a
Terminal instance but this is a workable fix in the mean time.
Fixes#11705
Add bg_color and fg_color options to GhosttyRenderStateRowCellsData
that resolve the final RGB color for a cell, flattening the multiple
possible sources. For background, this handles content-tag bg_color_rgb,
content-tag bg_color_palette (looked up in the palette), and the
style bg_color. For foreground, this resolves palette indices through
the palette; bold color handling is not applied and is left to the
caller.
Both return GHOSTTY_INVALID_VALUE when no explicit color is set, in
which case the caller should fall back to whatever default color it
wants (e.g. the terminal background/foreground).
Fixes#11704
The RenderState empty initializer set both background and foreground
to the default RGB value of black (0, 0, 0), making text unreadable
when a caller has not explicitly configured terminal colors via
DynamicRGB. This is the common case for libghostty consumers.
Default the foreground to white so that the initial render state
provides readable white-on-black text out of the box.
Long term we also need to expose setting the default colors for a
Terminal instance but this is a workable fix in the mean time.
Fixes#11706
Add a new GHOSTTY_TERMINAL_DATA_MOUSE_TRACKING option to the
ghostty_terminal_get API. This returns true if any mouse tracking mode
is active (X10, normal, button, or any-event), replacing the need for
consumers to loop over four separate mode queries.
#11706
Add a new GHOSTTY_TERMINAL_DATA_MOUSE_TRACKING option to the
ghostty_terminal_get API. This returns true if any mouse tracking
mode is active (X10, normal, button, or any-event), replacing the
need for consumers to loop over four separate mode queries.
Multiple changes:
* `zig build -Demit-lib-vt` now produces both shared and static
libraries by default
* Ghosty as a zig build dependency exports the static lib as
`dep.artifact("ghostty-vt-static")`
* CMake exports the static lib as `ghostty-vt-static`
Note that the static library is _not fat_. **If you enable SIMD you have
dependencies** and you need to manually link those: libc++, simdutf, and
highway. The `c-cmake-static` example disables SIMD.
The static library was built without position-independent code,
which caused linker errors when consumers tried to link it into
PIE executables (the default on most Linux distributions). The
linker would fail with "relocation R_X86_64_32 against symbol
cannot be used when making a PIE object."
Enable PIC on the static library root module so it can be linked
into both PIE and non-PIE executables.
Expose both shared and static libraries as separate CMake imported
targets (ghostty-vt and ghostty-vt-static) rather than toggling
between them with BUILD_SHARED_LIBS. The zig build already produces
both in a single invocation, so both are always available.
The find_package config template is updated to export both targets
as ghostty-vt::ghostty-vt and ghostty-vt::ghostty-vt-static.
Add a c-vt-cmake-static example that demonstrates linking the static
library via FetchContent with -Dsimd=false to avoid C++ runtime
dependencies.
Refactor GhosttyLibVt to support both shared and static library
builds via a shared initLib helper that accepts a LinkMode. The
shared and static entry points (initShared, initStatic) delegate
to this common path.
For static builds, compiler_rt and ubsan_rt are bundled to avoid
undefined symbol errors. Debug symbols (dsymutil) are skipped for
static libs since they are not linked. The install artifact uses
a "-static" suffix internally but installs as "libghostty-vt.a"
via a new installLib method. Wasm is excluded from static builds
since it has no meaningful static vs shared distinction.
Previously, every call to vt_write created a fresh ReadonlyStream with
new Parser and UTF8Decoder state. This meant escape sequences split
across write boundaries (e.g. ESC in one write, [27m in the next) would
lose parser state, causing the second write to start in ground state and
print the CSI parameters as literal text.
The C API now stores a persistent ReadonlyStream in the TerminalWrapper
struct, which is created when the Terminal is initialized. The vt_write
function feeds bytes through this stored stream, allowing it to maintain
parser state across calls. This change ensures that escape sequences
split across write boundaries are correctly parsed and rendered.
Previously, every call to vt_write created a fresh ReadonlyStream with
new Parser and UTF8Decoder state. This meant escape sequences split
across write boundaries (e.g. ESC in one write, [27m in the next)
would lose parser state, causing the second write to start in ground
state and print the CSI parameters as literal text.
The C API now stores a persistent ReadonlyStream in the TerminalWrapper
struct, which is created when the Terminal is initialized. The vt_write
function feeds bytes through this stored stream, allowing it to maintain
parser state across calls. This change ensures that escape sequences
split across write boundaries are correctly parsed and rendered.
Add GHOSTTY_BUILD_INFO_OPTIMIZE to query the Zig optimization mode
(debug, release safe/small/fast) the library was compiled with. This
reads directly from builtin.mode at comptime so it requires no build
system plumbing.
Add a new C API function ghostty_build_info() that exposes compile-time
build options to library consumers. This allows callers to query whether
SIMD, Kitty graphics protocol, and tmux control mode support were
enabled at build time.
Add a new C API function ghostty_build_info() that exposes compile-time
build options to library consumers. This allows callers to query whether
SIMD, Kitty graphics protocol, and tmux control mode support were
enabled at build time.
Remove the dedicated `zig build lib-vt` step and replace it with a
`-Demit-lib-vt` build option. This fixes two problems:
1. We can default XCFramework, app, etc. steps to false if emit-lib-vt
is true, so that the lib-vt build doesn't pull in unrelated artifacts.
**Most importantly, lib-vt alone can be build without full Xcode
installations.**
2. We can build lib-vt as part of a bundle with other artifacts if we
really want.
Remove the dedicated `zig build lib-vt` step and replace it with a
`-Demit-lib-vt` build option. This fixes two problems:
1. We can default XCFramework, app, etc. steps to false if emit-lib-vt
is true, so that the lib-vt build doesn't pull in unrelated
artifacts. **Most importantly, lib-vt alone can be build without
full Xcode installations.**
2. We can build lib-vt as part of a bundle with other artifacts if we
really want.
Add two new CellData variants to extract background color values
directly from cells. color_palette (10) returns the palette index as a
GhosttyColorPaletteIndex and color_rgb (11) returns the RGB components
as a GhosttyColorRgb. Both reuse the existing color types from color.h
rather than introducing new ones.
These are only valid when the cell content_tag is
bg_color_palette or bg_color_rgb respectively; querying them with a
mismatched tag reads from the wrong union member.
Found via Ghostling.
Add two new CellData variants to extract background color values
directly from cells. color_palette (10) returns the palette index
as a GhosttyColorPaletteIndex and color_rgb (11) returns the RGB
components as a GhosttyColorRgb. Both reuse the existing color
types from color.h rather than introducing new ones.
These are only valid when the cell content_tag is
bg_color_palette or bg_color_rgb respectively; querying them
with a mismatched tag reads from the wrong union member.
Map CMake release build types (Release, MinSizeRel, RelWithDebInfo) to
-Doptimize=ReleaseFast so that zig build automatically produces
optimized builds when CMake is configured for a release variant. Debug
builds remain unaffected, letting Zig use its default Debug optimization
level.
Map CMake release build types (Release, MinSizeRel, RelWithDebInfo)
to -Doptimize=ReleaseFast so that zig build automatically produces
optimized builds when CMake is configured for a release variant.
Debug builds remain unaffected, letting Zig use its default Debug
optimization level.
Add a new CI job that builds the root CMakeLists.txt to ensure the cmake
wrapper for libghostty-vt works.
This isn't the recommend way to build libghostty-vt, but its how
downstream CMake projects would consume it so we gotta keep it working.
This adds a function to the core surface to get process information
about the process(es) running in the terminal. Currently supported is
the PID of the foreground process and the name of the slave PTY.
If there is an error retrieving the information, or the platform does
not support retieving that information `null` is returned.
This will be useful in exposing the foreground PID and slave PTY name to
AppleScript or other APIs.
Add a new CI job that builds the root CMakeLists.txt to ensure the
cmake wrapper for libghostty-vt works.
This isn't the recommend way to build libghostty-vt, but its how
downstream CMake projects would consume it so we gotta keep it
working.
Add a top-level CMakeLists.txt that wraps `zig build lib-vt` so that
CMake-based downstream projects can consume libghostty-vt without
needing to interact with the Zig build system directly. A custom command
triggers the zig build during `cmake --build`, and the resulting shared
library is exposed as an IMPORTED target.
Downstream projects can pull in the library via FetchContent, which
fetches the source and builds it as part of their own CMake build, or
via find_package after a manual install step. The package config
template in dist/cmake/ sets up the ghostty-vt::ghostty-vt target with
proper include paths and macOS rpath handling.
A c-vt-cmake example demonstrates the FetchContent workflow, creating a
terminal, writing VT sequences, and formatting the output as plain text.
CI is updated to auto-discover and build CMake-based examples alongside
the existing Zig-based ones.
> [!WARNING]
>
> I am **very much not a CMake expert.** I leaned on LLMs heavily for
this. I did read the docs for what was chosen here and understand what's
going on, but if there is a better or more idiomatic way to do this I'm
all ears!
## Example CMake File
```cmake
cmake_minimum_required(VERSION 3.19)
project(c-vt-cmake LANGUAGES C)
include(FetchContent)
FetchContent_Declare(ghostty
GIT_REPOSITORY https://github.com/ghostty-org/ghostty.git
GIT_TAG main
)
FetchContent_MakeAvailable(ghostty)
add_executable(c_vt_cmake src/main.c)
target_link_libraries(c_vt_cmake PRIVATE ghostty-vt)
```
Add a top-level CMakeLists.txt that wraps `zig build lib-vt` so that
CMake-based downstream projects can consume libghostty-vt without
needing to interact with the Zig build system directly. A custom
command triggers the zig build during `cmake --build`, and the
resulting shared library is exposed as an IMPORTED target.
Downstream projects can pull in the library via FetchContent, which
fetches the source and builds it as part of their own CMake build, or
via find_package after a manual install step. The package config
template in dist/cmake/ sets up the ghostty-vt::ghostty-vt target
with proper include paths and macOS rpath handling.
A c-vt-cmake example demonstrates the FetchContent workflow, creating
a terminal, writing VT sequences, and formatting the output as plain
text. CI is updated to auto-discover and build CMake-based examples
alongside the existing Zig-based ones.
The GRAPHEMES_BUF data kind previously required a double pointer
(pointer to a uint32_t*) because the OutType was [*]u32, making the
typed out parameter *[*]u32. Change OutType to u32 so that callers
pass a plain uint32_t* buffer directly, which is the natural C
calling convention. The implementation casts the out pointer to
[*]u32 internally to write into the buffer.
The STYLE data kind read directly from the render state style array
without checking whether the cell actually had non-default styling.
The style data is undefined for unstyled cells, so this caused a
panic on a corrupt enum value when the caller read the style of an
unstyled cell. Now check cell.hasStyling() first and return the
default style for unstyled cells.
Expand the c-vt-render example to exercise dirty tracking, color
retrieval, cursor state, row/cell iteration with style resolution,
and dirty state reset. Break the example into six doxygen snippet
regions and reference them from render.h.
Expose the cursor fields from RenderState.Cursor through the C API
via new GhosttyRenderStateData enum values. This adds getters for
visual style, visibility, blink state, password input detection,
and viewport position (x, y, wide tail).
A new GhosttyRenderStateCursorVisualStyle enum maps the Zig
cursor.Style values (bar, block, underline, block_hollow) to
stable C integer constants. Viewport position getters return
GHOSTTY_INVALID_VALUE when the cursor is not visible within
the viewport.
Add individual color data kinds to GhosttyRenderStateData so callers
can query background, foreground, cursor color, cursor-color presence,
and the full 256-color palette through ghostty_render_state_get()
without using the sized-struct colors API.
COLOR_CURSOR returns GHOSTTY_INVALID_VALUE when no explicit cursor
color is set; callers can check COLOR_CURSOR_HAS_VALUE first.
Add next, select, and get functions to the render state row cells
API, mirroring the row iterator pattern. row_cells_next advances to
the next cell sequentially, row_cells_select jumps to a specific
column index with bounds validation, and row_cells_get queries data
for the current cell position.
The get function supports querying raw cell values (GhosttyCell),
resolved styles (GhosttyStyle), grapheme codepoint counts, and
writing grapheme codepoints into a caller-provided buffer.
Also add Cell.C and Cell.cval() to page.zig, matching the existing
Row.C/Row.cval() pattern, so the render state can convert cells to
the C ABI type without a raw bitCast.
Currently I have to use [this unusual
syntax](6e1c9f32e0/flake.nix (L137))
in my flake inputs to ensure that I don't have systems repeated in my
flake.lock file. This will make more obvious the fact that you have to
do follows to that hidden input.
Change row_iterator_new to only allocate with undefined fields,
matching the pattern used by row_cells_new. The iterator is now
populated via the render state get API with a new .row_iterator
data kind, which slices the row data and resets y to null.
This separates the lifetime of the opaque handle from the render
state it iterates, letting callers allocate once and re-populate
from different states without reallocating.
Add a new opaque RowCells type that wraps per-row cell data
(raw cells, graphemes, styles) for the C API. The caller
allocates a RowCells handle via row_cells_new, then populates
it by passing it to row_get with the new .cells data kind.
This queries the current row from the iterator and slices the
underlying MultiArrayList into the RowCellsWrapper fields.
The new type and functions are wired through main.zig,
lib_vt.zig, and the render.h C header.
Replace ghostty_render_state_row_dirty_get and
ghostty_render_state_row_dirty_set with generic
ghostty_render_state_row_get and ghostty_render_state_row_set
functions using enum-dispatched data/option kinds.
Replace the individual ghostty_render_state_size_get,
ghostty_render_state_dirty_get, and ghostty_render_state_dirty_set
functions with generic ghostty_render_state_get and
ghostty_render_state_set functions that use enum-dispatched data
kinds and option kinds, following the same InType/OutType pattern
used by the terminal and mouse encoder C APIs.
When some tools spawn subshells, PROMPT_COMMAND may be inherited as an
environment variable while the __ghostty_hook function is not (bash
doesn't export functions by default). This causes "command not found"
errors on every prompt in the subshell.
Add 2>/dev/null to the __ghostty_hook entry in PROMPT_COMMAND so that it
silently no-ops in subshells where the function isn't defined. This also
silences any errors from inside __ghostty_hook itself, but those are all
terminal escape sequences and non-actionable.
See: #11245
When some tools spawn subshells, PROMPT_COMMAND may be inherited as an
environment variable while the __ghostty_hook function is not (bash
doesn't export functions by default). This causes "command not found"
errors on every prompt in the subshell.
Add 2>/dev/null to the __ghostty_hook entry in PROMPT_COMMAND so that it
silently no-ops in subshells where the function isn't defined. This also
silences any errors from inside __ghostty_hook itself, but those are all
terminal escape sequences and non-actionable.
See: #11245
