01 / Toolchain

Commands

Build the tools with make, then run build/bin/ziran, or install it with make install-user. ziran guide prints a short tour of these commands.

ziran version

Print the compiler version; --version is the same. Release tags follow it, so ref = "v0.2.0" in ziran.toml pins a release.

ziran check --root DIR file.zi ...

Check source and its imports without writing output. Add --diagnostics=json for machine-readable diagnostics.

ziran ir --root DIR -o DIR file.zi|file.zir ...

Check and write versioned binary .zir modules.

ziran build --target=c|cpp|go|rust|py|plan9-c --root DIR -o DIR file.zi|file.zir ...

Generate target source. --exe --entry module:function writes a runnable Go or Rust project, or a Python __main__.py that python3 DIR runs; Go also takes --pkg NAME. plan9-c is experimental.

ziran bundle --root DIR --entry module:function -o FILE file.zi|file.zir ...

Link a supported program into a version 24 .zib bundle. --bind module:function=module:function redirects a host capability.

ziran run FILE.zib

Validate and run a bundle. The entry result, if any, is printed after the program output.

ziran fmt [--check] file.zi ...

Format source with stable indentation and spacing; --check reports files that need formatting.

ziran inspect [--hex] file.zir

Show a saved .zir module as readable declarations and expression graphs, or as bytes and offsets.

ziran api [--json] --root DIR file.zi|file.zir ...

List the checked public constants, globals, types, and procedures of each loaded module. The standard library reference is generated this way.

ziran features [--id ID] [--json]

Report the versioned feature registry: syntax, status, target support, limits, and accepted and rejected examples.

ziran capabilities [--target=c|cpp|go|rust|py|zib|plan9-c] [--json]

Report what each target supports and its limits.

ziran explain CODE | --list [--json]

Explain a diagnostic code, or list every registered code.

Repeat --module-path DIR to search for imported modules outside the root, and use --define NAME to select conditional source. Checking is unconditional; the toolchain rejects --strict and --no-strict.

02 / Projects

Project commands

A project has a ziran.toml and a committed ziran.lock that pins every dependency and the compiler to full Git commits. Add --project [--locked] [--offline] to check, ir, build, bundle, or api to use it.

ziran add URL

Add a dependency from any Git repository: an HTTPS or SSH URL, HOST/OWNER/REPO, or OWNER/REPO on GitHub. HTTPS and SSH name the same package. Its modules import as NAME/Module; ziran pkg list shows them. --name renames the dependency and --source pins a non-Ziran source tree. A dependency ref can be a tag, a branch, or a full 40-character commit hash.

ziran lock

Resolve dependencies and write ziran.lock.

ziran update [NAME|ziran]

Refresh every package, one package and its dependencies, or only the compiler.

ziran fetch

Download the locked checkouts into the cache for offline use.

ziran pkg path NAME

Print the checkout the lock selects for a package.

ziran tool NAME COMMAND

Build a package tool if needed, check its settings, and run it from the project root.

ziran install [--prefix DIR]

Run the project tool’s install command, into ~/.local by default.

Packages and project imports ↗

03 / Direct tools

Compiler binaries

ziran dispatches to these tools in build/bin; they accept the same options.

zi2zir

Check source and write .zir; --check-only writes nothing.

zi2c · zi2cpp · zi2go · zi2rust · zi2py

Generate C (including Plan 9 C with --target=plan9-c), C++, Go, Rust, and Python 3.10. --no-main leaves out the entry wrapper.

zi2zib bundle | run

Link and run portable bundles.

zi-api · zi-inspect · zi-fmt

The API listing, .zir inspector, and formatter.

Toolchain source guide ↗

04 / Embedding

Portable C host API

Include ziran_host.h and link build/libziran.a. The host API validates version 24 bundles and requires every linked capability to be bound before execution.

Bundle *BundleOpen(const char *path)

Open and validate a bundle. Returns an opaque handle or failure.

void BundleClose(Bundle *bundle)

Release a bundle and its names.

size_t BundleCapabilityCount(const Bundle *bundle)

Number of required host capabilities.

const char *BundleCapabilityModule(const Bundle *bundle, size_t index)

Module name for a required capability.

const char *BundleCapabilityFunction(const Bundle *bundle, size_t index)

Function name for a required capability.

int BundleRun(const Bundle *bundle, const HostBinding *bindings, size_t count, long long *result, int *has_result)

Run with fresh globals. Integer and boolean entry values populate result; a void entry sets has_result to zero.

BundleInstance *BundleInstantiate(const Bundle *bundle, const HostBinding *bindings, size_t count)

Create an instance whose module globals persist between runs. Keep the bundle and binding contexts alive until close.

int BundleInstanceRun(BundleInstance *instance, long long *result, int *has_result)

Run one entry call. A runtime failure makes that instance unusable.

void BundleInstanceClose(BundleInstance *instance)

Release the instance.

Host values and callbacks

HostBinding contains module, function, a VmHostCall callback, and context. The callback receives typed arguments and writes a typed result. The value kinds are VM_HOST_VOID, VM_HOST_INTEGER, VM_HOST_UNSIGNED, VM_HOST_REAL, VM_HOST_STRING, VM_HOST_RECORD, and VM_HOST_SLICE.

typedef int (*VmHostCall)(void *context, const char *module,
                          const char *function, const VmHostValue *args,
                          int arg_count, VmHostValue *result);

typedef struct HostBinding {
    const char *module;
    const char *function;
    VmHostCall call;
    void *context;
} HostBinding;

VmHostValue has kind: VmHostValueKind, type: const char *, integer: int64_t, bits: uint64_t, real: double, data: const unsigned char *, length: size_t, fields: const VmHostField *, field_count: size_t, and elements: VmHostValue *. Each VmHostField has name and value.

Record fields are in declaration order and include names and types. Synchronous numeric, boolean, and string slice arguments may be edited in place; keep the element pointer and length unchanged. The VM validates and copies edits back. Host pointer, array, and slot calls are unsupported. Returned string bytes and record fields must remain valid until BundleRun returns.

Read the complete C header ↗