AGENTS.md

1# libghostty-vt C API
2 
3- C API must be designed with ABI compatibility in mind
4- Zig tagged unions must be converted to C ABI compatible unions
5  via `lib.TaggedUnion`.
6- Any functions must be updated all the way through from here to
7  `src/terminal/c/main.zig` to `src/lib_vt.zig` and the headers
8  in `include/ghostty/vt.h`. Specifically:
9  1. Define the function in `src/terminal/c/<module>.zig`.
10  2. Re-export it via a `pub const` in `src/terminal/c/main.zig`.
11  3. Add an `@export` call in `src/lib_vt.zig` with the
12     `ghostty_` prefixed symbol name.
13  4. Declare it in the corresponding header under `include/ghostty/vt/`.
14- In `include/ghostty/vt.h`, always sort the header contents by:
15  (1) macros, (2) forward declarations, (3) types, (4) functions
16 
17## ABI Compatibility
18 
19- Prefer opaque pointers for long-lived objects, such as
20  `GhosttyTerminal`.
21- Structs:
22  - May contain padding bytes if we're confident we'll never grow
23    beyond a certain size.
24  - May use the "sized struct" pattern: an `extern struct` with
25    `size: usize = @sizeOf(Self)` as the first field. In the C header,
26    callers use `GHOSTTY_INIT_SIZED` from `types.h` to zero-initialize and
27    set the size.
28