clj-zig.layout — com.leifericf/clj-zig 2026.06.27-alpha1

Describe the memory layout of a named boundary type (pure). A field list goes in, a layout descriptor comes out, or a diagnostic is thrown.

The descriptor carries the fields in declaration order with their normalized types and C-ABI byte offsets, plus the whole struct's size and alignment:

(describe 'Point '[x :f64 y :f64])
=> {:name Point
    :fields [{:name x :type {:kind :scalar :name :f64} :offset 0}
             {:name y :type {:kind :scalar :name :f64} :offset 8}]
    :size 16 :align 8}

A field may be a carrier scalar, an enum's i32 backing, or a buffer field (:string, [:bytes [:slice :u8]], or a bare, owned, or borrowed slice of a carrier scalar). A buffer field has no single C type: it expands in the wire struct to two usize words, a pointer and a length, so the descriptor records both offsets and the marshalled Clojure target for each. The descriptor renders the extern struct the generated Zig uses and drives the field marshalling FFM performs; the layout matches Zig's extern struct (C ABI).

describe clj

(describe type-name fields)

(describe type-name fields types)

Build the layout descriptor for a named type from its fields, a vector of name type pairs. A carrier scalar or an enum keeps its carrier size and alignment (an enum crosses as its i32 backing); a buffer field (:string, [:bytes [:slice :u8]], or a slice) expands to two usize words aligned to the word width, and the field records the pointer offset as :offset, the length offset as :len-offset, and the marshalled target. Throws a diagnostic for an odd field list or a field the wire struct cannot carry. The optional types map resolves named enum fields against the registry of named types already declared in the namespace.

describe-enum clj

(describe-enum type-name members)

The descriptor for a defenumz type: an i32-backed enum whose members cross as keywords. Throws for an odd member list or a member with a non-integer value.

describe-record clj

(describe-record type-name fields record-ns)

(describe-record type-name fields record-ns types)

The layout descriptor for a defrecordz type: the struct layout of describe, plus the qualified map-factory symbol the boundary resolves to rebuild the record from its fields on a return.

enum? clj

(enum? descriptor)

True when a layout descriptor describes a defenumz enum rather than a struct or record.

zig-decl clj

(zig-decl descriptor)

The Zig declaration for a named type: an enum for a defenumz, a regular struct (the nice record the body constructs) for a buffer-carrying deftypez/defrecordz, and an extern struct (the wire layout, which is also the nice layout) for a scalar-only struct.

zig-enum clj

(zig-enum {type-name :name :keys [values]})

The enum(i32) declaration the generated Zig uses for an enum layout.

zig-nice-struct clj

(zig-nice-struct {type-name :name :keys [fields]})

The nice record struct the body constructs and returns: a regular struct (not extern) whose buffer fields are real Zig slices, not the usize ptr/len words of the wire struct. Emitted for a buffer-carrying record so the body can build the nice type the wrapper then decomposes field by field into the wire extern struct. A scalar-only record keeps its extern struct (the nice and wire layouts coincide, and the body builds it directly).

zig-struct clj

(zig-struct {type-name :name :keys [fields]})

The extern struct declaration the generated Zig uses for a layout. Each scalar field is declared by its carrier; each buffer field expands to a usize pointer and length pair, the wire form a slice parameter already takes.