clj-zig.core — com.leifericf/clj-zig 2026.06.02-alpha1

The defnz and defz defining forms. These macros stay thin: they parse the form into data, hand it to the pure pipeline (signature, then spec, then source) and the shell (compile or cache, then load, then bind), then rebind an ordinary Clojure Var. A user can reach every stage through the data functions without the macro.

defnz defines a Clojure function backed by a Zig body. defz registers Zig declarations that the bodies in its namespace may call but that are not themselves callable from Clojure.

artifact clj

(artifact spec body)

(artifact spec body gen)

Compile or reuse the native library for spec and body. Returns the inspection data describing the build: the spec, the body, the generated source, the library and source paths, the symbol, whether the library was reused (:cached) or freshly built (:compiled), and the external modules it links (:modules) when the namespace declares any.

build-inputs clj

(build-inputs spec body)

(build-inputs spec
              body
              {:keys [mode entry options-extra aux-files] :or {mode :inline}})

The cache/compile inputs for spec and body: the generated source, prefixed with this namespace's defz declarations, plus the compiler identity that the content hash includes. The Zig version in the hash is the pinned version, not a live zig version: every machine pins the same compiler, so a baked library and a function built in place hash alike, and a consumer with no compiler reproduces the hash without running Zig. gen selects the source shape: inline splices the body string into a wrapper; file concatenates the user's file text and a wrapper that calls its pub fn; raw uses the file text as-is. gen also carries any C-interop :options-extra. Options layer by precedence: the optimize default, then the namespace zig-deps, then the descriptor, so a function inherits its namespace's link flags and may still override them. A file body that imports other Zig files carries them as :aux-files, reproduced beside the source.

defenumz clj macro

(defenumz type-name & tail)

Define an enum boundary type backed by an integer scalar (default :i32). Members cross as keywords named for each member; the Var holds the descriptor. The optional options map may carry :backing to widen or narrow the tag (:u8, :u32, ...), matching the C enum widths real libraries use.

 (defenumz ParseStatus
   [ok 0
    invalid 1
    eof 2])

 (defenumz CompactTag
   [a 0 b 1 c 2]
   {:backing :u8})

defnz clj macro

(defnz fn-name & tail)

Define a Clojure function whose body is Zig. The signature vector is the boundary contract; the trailing form is the Zig body, a string or a {:zig/file "name.zig"} descriptor, and may be omitted to source the body from the namespace's co-located .zig:

(defnz add
  [x :i64
   y :i64
   :ret :i64]
  "return x + y;")

(defnz dot
  [a [:slice :const :f64]
   b [:slice :const :f64]
   :ret :f64]
  {:zig/file "dot.zig"})

;; body in app/geometry.zig's `pub fn hypotenuse`
(defnz hypotenuse
  [a :f64 b :f64 :ret :f64])

;; signature inferred from app/geometry.zig's `pub fn hypotenuse`
(defnz hypotenuse)

A file holds a complete Zig pub fn the generated wrapper calls; a bodyless form calls the pub fn of the same name in the .zig beside the namespace's source, inferring the signature from it when the signature is omitted too. The descriptor may also carry C-interop options (:c/link, :c/include-path, ...), an entry name (:zig/fn), and a raw escape hatch (:zig/raw, :zig/symbol). Redefining recompiles; a failed recompile keeps the last good binding.

Multi-arity (ADR 51) mirrors defn:

(defnz add
  ([x :i64 :ret :i64] "return x;")
  ([x :i64 y :i64 :ret :i64] "return x + y;"))

Each arity compiles independently and the Var dispatches by argument count. File-body descriptors are not supported in multi-arity.

defrecordz clj macro

(defrecordz type-name & tail)

Define both a Clojure record and a named boundary type sharing its layout. A signature in this namespace may name the record as an argument or return type; a record-typed return rebuilds the record on the Clojure side instead of returning a plain map.

(defrecordz Point
  [x :f64
   y :f64])

Unlike deftypez/defenumz, the optional docstring does NOT land on the type symbol: defrecord interns the type as a Class, and a class symbol has no Var to carry :doc. The docstring is attached to the map->Type factory Var instead, the interned Var closest to the type and the one the FFM return path resolves when rebuilding a record.

deftypez clj macro

(deftypez type-name & tail)

Define a named boundary type with an extern struct layout. The signatures in this namespace may name it as an argument or return type; the Var holds the layout descriptor.

An optional trailing options map may carry :packed true to emit a Zig packed struct with no alignment padding. Packed structs support scalar and enum fields only.

(deftypez Point
  [x :f64
   y :f64])

(deftypez RGB
  [r :u8 g :u8 b :u8]
  {:packed true})

defz clj macro

(defz decl-name decl-source)

Register a Zig declaration usable by the defnz bodies in this namespace. It is not callable from Clojure; the Var holds its source. The source is a string or a {:zig/file "shared.zig"} descriptor, the natural home for a shared @cImport block and helper fns.

deps-in clj

(deps-in ns-sym)

The namespace-level C-interop options registered for ns-sym, or nil.

establish! clj

(establish! spec body)

(establish! spec body gen)

Build the artifact for spec and body and bind its symbol. Returns the inspection data plus the native invoker under :invoke. Throws the compile diagnostic when the Zig does not build.

establish-binding! clj

(establish-binding! the-var spec body var-meta wrap)

(establish-binding! the-var spec body var-meta wrap gen)

Establish the native function for the-var and rebind it. wrap turns the raw invoker into the public fn (it carries the arglist and any destructuring). On success the root is swapped, inspection metadata is merged, and any stale failure is cleared. On failure the last good root is left untouched, the failed attempt is recorded for inspection, and the rendered diagnostic is rethrown so the REPL shows it at once.

establish-binding-from! clj

(establish-binding-from! the-var spec descriptor defining-file var-meta wrap)

Resolve a {:zig/file ...} descriptor relative to defining-file, read the Zig source, and establish the binding for the-var. File mode generates a wrapper that calls the user's pub fn; :zig/raw skips the wrapper and binds :zig/symbol (or the spec's symbol) directly. The body's relative @imports are resolved and carried along so they compile in the cache directory. An optional //! clj-zig: <ns> header in the file must match the using namespace. Public because the defnz expansion calls it at load time, so re-evaluating the form re-reads the file and its imports.

establish-comptime-binding! clj

(establish-comptime-binding! the-var spec body comptime-params var-meta wrap)

Bind a comptime-specialized defnz Var. The body is compiled once per distinct set of comptime values (cached by content hash). At each call, comptime values are spliced into the body as const declarations, the modified body is compiled or reused from cache, and the non-comptime arguments are passed to the invoker.

spec contains only the non-comptime params (the FFM boundary). comptime-params is a vector of {:binding :type} for the comptime params. body is the Zig body template.

establish-multi-binding! clj

(establish-multi-binding! the-var arity-specs var-meta)

Establish a multi-arity defnz function (ADR 51). Each arity is compiled independently into its own native library with its own invoke fn; the Var's root fn dispatches by argument count. On redefinition, each arity is recompiled independently: a failed arity keeps its previous invoke fn while successful arities get new ones, so a redefinition that breaks one arity leaves the others callable.

gen-from-info clj

(gen-from-info {:keys [source-mode entry source-file options-extra aux-files]})

The build gen map reconstructed from a Var's inspection info: the source mode plus the file-mode keys (:entry, :source-file, :options-extra, :aux-files) that establish-binding! recorded. The single source for how recompile! and bake re-derive a function's build mode, so a new gen key lands in one place and the bake-equals-recompile hash invariant cannot drift (docs/04).

modules-in clj

(modules-in ns-sym)

The namespace-level external Zig modules registered for ns-sym, keyed by import name, or nil.

recompile! clj

(recompile! the-var)

Force a fresh build of the-var's current spec and body, ignoring the cached artifact, and rebind. Returns the Var. Rebuilds in the same mode the function was defined with (inline, file, or raw). A multi-arity Var rebuilds every arity. A comptime Var clears its per-value cache and rebinds, so each distinct comptime combination rebuilds lazily on its next call (the values to build for are not known until called).

register-decl! clj

(register-decl! ns-sym decl-name decl-source)

Register or replace a defz declaration in its namespace, preserving declaration order so the generated preamble is stable. Public because the defz expansion calls it from the user's namespace.

register-deps! clj

(register-deps! ns-sym descriptor)

Register the namespace-level C-interop options, optimize mode, and external Zig modules for ns-sym, replacing any previous registration. Public because the zig-deps expansion calls it from the user's namespace.

register-type! clj

(register-type! ns-sym descriptor)

Register or replace a deftypez layout descriptor in its namespace. Public because the deftypez expansion calls it from the user's namespace.

resolve-decl-source clj

(resolve-decl-source decl-source defining-file)

The Zig text for a defz declaration: a string as-is, or the contents of the {:zig/file ...} it names, resolved relative to defining-file. Public because the defz expansion calls it at load time.

types-in clj

(types-in ns-sym)

The map of named-type descriptors declared in ns-sym, keyed by name.

zig-deps clj macro

(zig-deps descriptor)

Declare the dependencies shared by every defnz in this namespace. The C-interop options let a co-located .zig @cImport a header and link its library without repeating the flags on each function; :zig/modules declares external Zig packages the bodies may @import by name (ADR 34):

(zig-deps {:c/link ["m"]
           :zig/modules {"phane" {:path "../phane/src/root.zig"}}})

A function descriptor still overrides the C options. The options enter each function's content hash, so changing them recompiles the namespace's functions.