Targets

A target generates the code of an API, from its IR, for one language, and checks it: that it builds, that its records have the layout recorded in the IR, and that it works. The C and Zig targets also check the functions against the headers: C that the IR gives them the types the headers do, see capi, and Zig that its bindings agree with Zig’s own translation of the headers, see zig. Targets are found through the yace.targets entry point group, so a package can provide one without changes to yace; see yace.targets.target.

Each target has two layers. The raw one calls the C functions as they are, and needs nothing beyond the declarations. The idiomatic one, over it, is what a programmer of the language expects: handles released when they go out of scope, errors raised or returned, results returned rather than written through pointers, closures for callbacks. It is generated from what the header says beyond C, see The C Subset, as derived in yace.targets.idiom, the same for every language.

The targets are C, capi, Python, python, Cython, cython, Rust, rust, C++, cpp, Zig, zig, and Go, go. The C target has a narrower sibling, capi_pp, which generates only its pretty-printers, for an API to compile into its own library.

The fixture

What a target’s own check cannot show is that the bindings work with a library built from the original header. The example library, examples/libfoo, uses every construct of the C subset, and is that library. Each target has a check program in examples/libfoo/checks/<target>/, written in the target’s language against the bindings it generates. The program calls the library, exercising callbacks of each @lifetime (see Callback lifetimes), out-parameters, opaque handles, strings and records, and prints what it got back. Records are printed with the pretty-printers the target generates.

All checks print the same YAML documents, those in examples/libfoo/expected.yaml, or the same as JSON objects when given the argument json. tests/test_fixture.py builds the library as a shared library, generates each target’s bindings, builds and runs its check, and compares the output to the expected documents.

The expected documents are what the library returns, so they hold no pointer values, which differ between runs.

The interface of a yace target: what generates the bindings of an API for one language from its IR. Targets are found through the yace.targets entry point group, so a package can provide one without changes to yace.

class yace.targets.target.Target(output: Path, include: List[Path] | None = None, options: Dict[str, str] | None = None)

Emit code for the IR into ‘<output>/<NAME>’, and check what it emitted

abstractmethod check(model) → list

Build and exercise what emit() wrote; returns the failures, if any

abstractmethod emit(model) → list

Emit the code for ‘model’; returns the paths written

headers_missing(model) → str | None

Why the headers the IR was parsed from cannot be compiled with, or None where every one of them is found in the include directories

headers_unchecked(model) → str | None

Why the signatures cannot be checked against the headers the IR was parsed from, or None where every one of them is found

classmethod options_of(given: Dict[str, str]) → Dict[str, str]

Every option of the target, those not given at their default; raises ValueError for a key it does not take, or a value it does not accept

yace.targets.target.targets() → Dict[str, EntryPoint]

The installed targets by name, loaded when asked for

How the functions of an API are called idiomatically, in any language, from what the IR knows of them; each target renders it in its own language.

From the semantics of the C subset, see yace.ir.semantics:

  • An opaque record is a handle, also by a typedef of its own name, such as typedef struct foo foo;. A function creating one through an [out] pointer constructs it, the one that @destroys it releases it, and those taking it as their first parameter are its methods. The rest are functions.

  • What a function writes through an [out] pointer is returned, not passed: a record, a value, a handle, or the elements of an array, as many as the function says it wrote: its count written, or else the count it returns, or else the capacity. Python allocates the array, of the capacity given; Rust, C++, Go and Zig take it from the caller, as a buffer whose length is the capacity, and return the part written.

  • An array read through a pointer is given as a sequence, its @arrparam length then known from the sequence, and not given.

  • A @recparam record is given, and its size is that of the record’s type, as C’s sizeof, and not given.

  • A callback is given as a closure, kept for as long as its @lifetime says; its void * context is the binding’s to pass, not given. A callback without a @lifetime is given as the raw function pointer, with its context.

  • With @errno, a negative return is an error. A function returning int returns only that status, so nothing when it succeeds; any other integer is a value, such as a count, and returned. With @errno partial, the error carries what the call returns when it succeeds.

  • A returned const char * is a string, and a returned pointer that is @nullable is nothing when NULL.

Names lose the prefix of the API, and methods also the name of their handle: foo_handle_close() is the method close of handle. A function taking a @recparam also loses the suffix _sized: foo_read_sized() is read, the name of the static inline function that C calls it through.

class yace.targets.idiom.Arg(*, param: str, index: int, kind: Literal['self', 'value', 'string', 'sequence', 'callback', 'length', 'size', 'context', 'capacity', 'count', 'out'], typ: Builtin | Pointer | Array | Record | EnumRef | TypedefRef | FunctionType, nullable: bool = False, of: str | None = None, shared: List[str] = [], lifetime: str | None = None)

How a parameter of the C function is given, when called idiomatically

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class yace.targets.idiom.Call(*, function: str, name: str, kind: Literal['constructor', 'destructor', 'method', 'function'], handle: str | None = None, args: List[Arg], outs: List[Out], errno: bool = False, partial: bool = False, returns: Literal['nothing', 'value', 'string', 'pointer', 'handle', 'count'], nullable: bool = False, ret: Builtin | Pointer | Array | Record | EnumRef | TypedefRef | FunctionType, memory: Memory | None = None)

A C function, as called idiomatically

counted(arg: Arg) → bool

Whether ‘arg’ is a string with a length, which C reads as bytes, not to a NUL; the binding takes a string that has a length of its own

given(buffers: bool = False) → List[Arg]

The arguments the caller gives; the binding passes or returns the rest. With ‘buffers’, as Rust, C++, Go and Zig take them, the caller gives each [out] array, as a buffer, and its capacity is the buffer’s length

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

out(param: str) → Out

What the function writes through the [out] parameter ‘param’

sized(arg: Arg) → Annotated[Builtin | Pointer | Array | Record | EnumRef | TypedefRef | FunctionType, FieldInfo(annotation=NoneType, required=True, discriminator='key')]

The type of the record whose size the ‘size’ argument ‘arg’ is, without its const

class yace.targets.idiom.Idioms(model: Model)

The idiomatic calls of the functions of ‘model’, and its handles

closure(param: Param, params: List[Param]) → bool

Whether a callback is given as a closure: one typedef’d, with a @lifetime and its context; any other is given raw

decl(function: str) → Function

The function of the C name ‘function’, which a record may share

distinct(raw: set)

Keep the C name for calls whose idiomatic one is shared, within the module or a handle, or is the C name of another function; a constructor is in the scope of both, as some targets place it in the handle

handle_name(record: str) → str

The idiomatic name of a handle, without the prefix: ‘handle’

of(handle: str) → Dict[str, List[Call]]

The calls of ‘handle’, by kind

owner(release: Call) → Call | None

The call that allocates or registers what ‘release’ frees, resizes or unregisters

partner(call: Call, role: str) → Call | None

The call of the role ‘role’ in the buffer or registration pattern of ‘call’

class yace.targets.idiom.Out(*, param: str, kind: Literal['record', 'value', 'handle', 'array'], typ: Builtin | Pointer | Array | Record | EnumRef | TypedefRef | FunctionType, capacity: str | None = None, count: str | None = None)

What the idiomatic function returns for an [out] parameter

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

yace.targets.idiom.call_doc(call: Call, doc: Doc, pname: Callable[[str], str], partial: str = '', buffers: bool = False) → Tuple[Doc, str]

The doc of ‘call’, and what it fails with: the parameters given, by their names in the binding, and with @errno, what the C function says it returns, as how it fails, since the binding returns the value and fails with the error; the text says both, and cannot be split. With @errno partial, the sentence ‘partial’ says where the error holds what the call wrote. With ‘buffers’, the caller gives the [out] arrays, see Call.given()

yace.targets.idiom.copyable(model: Model, typ) → bool

Whether a copy of a ‘typ’ holds all of it: not of a record declared but not defined, here or in another header, nor of one ending in a flexible array, whose elements follow it

yace.targets.idiom.is_lent(ret) → bool

Whether a returned pointer is to a record the caller may write: an object the library keeps or hands over, of which a copy would be another object

yace.targets.idiom.local(name: str, suffix: str, taken: Iterable[str]) → str

The name of a local made for the parameter ‘name’: ‘name_suffix’, with ‘_’ appended while that name is in ‘taken’, such as by another parameter. So long as no suffix is another suffix followed by ‘_’, no two locals share a name

yace.targets.idiom.typedefs_used(node) → Iterator[str]

The names of the typedefs ‘node’ refers to, among them those declared outside the headers, such as FILE