Gengoscript Quickstart

This page covers the shortest path to building Gengoscript, running a script, and checking that the local toolchain works.

For a guided first example, see tutorial-first-script.md.

Requirements

Build

Build the native CLI:

zig build -Dpreset=dev cli

Build the WASI runtime:

zig build -Dpreset=dev wasi

Build the embeddable engine artefacts:

zig build -Dpreset=dev engine-build
zig build -Dpreset=dev engine-native

Outputs:

  • zig-out/bin/gengo
  • build/gengo-runtime.wasm
  • build/gengo-engine.wasm
  • zig-out/lib/libgengo-engine.so on Linux

Run a Script

Native CLI:

./zig-out/bin/gengo script.gengo

WASI runtime:

wasmtime --dir . ./build/gengo-runtime.wasm -- script.gengo

The test, parity, and bench build steps also invoke wasmtime. If it is not on PATH, pass -Dwasmtime=/path/to/wasmtime to the relevant zig build command.

Run the CLI with no arguments to start the REPL:

./zig-out/bin/gengo

Validate the Build

Run the conformance suite:

zig build -Dpreset=dev test

Run parity checks between the embedded and host backends when relevant:

zig build -Dpreset=dev parity

Run benchmarks when you need performance data:

zig build -Dpreset=dev bench

For changes that touch the runtime, heap, or VM, also run:

zig build -Dpreset=stress test

Presets

  • dev is the default development preset.
  • tiny uses tighter heap and stack limits for constrained embeddings.
  • stress uses a larger inline heap and is the strongest check for memory behaviour.

Apply a preset with -Dpreset=<name>.

Next Steps

  • tutorial-first-script.md for a first script
  • embedding.md for Zig embedding
  • engine-api.md for C-compatible host integration