example/zig-vt

example/zig-vt/README.md

@@ -0,0 +1,14 @@
+# Example: `ghostty-vt` Zig Module
+
+This contains a simple example of how to use the `ghostty-vt` Zig module
+exported by Ghostty to have access to a production grade terminal emulator.
+
+Requires the Zig version stated in the `build.zig.zon` file.
+
+## Usage
+
+Run the program:
+
+```shell-session
+zig build run
+```

example/zig-vt/build.zig

@@ -0,0 +1,44 @@
+const std = @import("std");
+
+pub fn build(b: *std.Build) void {
+    const target = b.standardTargetOptions(.{});
+    const optimize = b.standardOptimizeOption(.{});
+
+    const run_step = b.step("run", "Run the app");
+    const test_step = b.step("test", "Run unit tests");
+
+    const exe_mod = b.createModule(.{
+        .root_source_file = b.path("src/main.zig"),
+        .target = target,
+        .optimize = optimize,
+    });
+
+    // You'll want to use a lazy dependency here so that ghostty is only
+    // downloaded if you actually need it.
+    if (b.lazyDependency("ghostty", .{})) |dep| {
+        exe_mod.addImport(
+            "ghostty-vt",
+            dep.module("ghostty-vt"),
+        );
+    }
+
+    // Exe
+    const exe = b.addExecutable(.{
+        .name = "zig_vt",
+        .root_module = exe_mod,
+    });
+    b.installArtifact(exe);
+
+    // Run
+    const run_cmd = b.addRunArtifact(exe);
+    run_cmd.step.dependOn(b.getInstallStep());
+    if (b.args) |args| run_cmd.addArgs(args);
+    run_step.dependOn(&run_cmd.step);
+
+    // Test
+    const exe_unit_tests = b.addTest(.{
+        .root_module = exe_mod,
+    });
+    const run_exe_unit_tests = b.addRunArtifact(exe_unit_tests);
+    test_step.dependOn(&run_exe_unit_tests.step);
+}

example/zig-vt/build.zig.zon

@@ -0,0 +1,24 @@
+.{
+    .name = .zig_vt,
+    .version = "0.0.0",
+    .fingerprint = 0x6045575a7a8387e6,
+    .minimum_zig_version = "0.14.1",
+    .dependencies = .{
+        // Ghostty dependency. In reality, you'd probably use a URL-based
+        // dependency like the one showed (and commented out) below this one.
+        // We use a path dependency here for simplicity and to ensure our
+        // examples always test against the source they're bundled with.
+        .ghostty = .{ .path = "../../" },
+
+        // Example of what a URL-based dependency looks like:
+        // .ghostty = .{
+        //     .url = "https://github.com/ghostty-org/ghostty/archive/COMMIT.tar.gz",
+        //     .hash = "N-V-__8AAMVLTABmYkLqhZPLXnMl-KyN38R8UVYqGrxqO36s",
+        // },
+    },
+    .paths = .{
+        "build.zig",
+        "build.zig.zon",
+        "src",
+    },
+}

example/zig-vt/src/main.zig

@@ -0,0 +1,26 @@
+const std = @import("std");
+const ghostty_vt = @import("ghostty-vt");
+
+pub fn main() !void {
+    // Use a debug allocator so we get leak checking. You probably want
+    // to replace this for release builds.
+    var gpa: std.heap.DebugAllocator(.{}) = .init;
+    defer _ = gpa.deinit();
+    const alloc = gpa.allocator();
+
+    // Initialize a terminal.
+    var t: ghostty_vt.Terminal = try .init(alloc, .{
+        .cols = 6,
+        .rows = 40,
+    });
+    defer t.deinit(alloc);
+
+    // Write some text. It'll wrap because this is too long for our
+    // columns size above (6).
+    try t.printString("Hello, World!");
+
+    // Get the plain string view of the terminal screen.
+    const str = try t.plainString(alloc);
+    defer alloc.free(str);
+    std.debug.print("{s}\n", .{str});
+}

src/lib_vt.zig

@@ -1,4 +1,13 @@
+//! This is the public API of the ghostty-vt Zig module.
+
+// The public API below reproduces a lot of terminal/main.zig but
+// is separate because (1) we need our root file to be in `src/`
+// so we can access other directories and (2) we may want to withhold
+// parts of `terminal` that are not ready for public consumption
+// or are too Ghostty-internal.
 const terminal = @import("terminal/main.zig");
+pub const Parser = terminal.Parser;
+pub const Terminal = terminal.Terminal;
 
 test {
     _ = terminal;