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@destroysit 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
@arrparamlength then known from the sequence, and not given.A
@recparamrecord is given, and its size is that of the record’s type, as C’ssizeof, and not given.A callback is given as a closure, kept for as long as its
@lifetimesays; itsvoid *context is the binding’s to pass, not given. A callback without a@lifetimeis given as the raw function pointer, with its context.With
@errno, a negative return is an error. A function returningintreturns 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@nullableis 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].
- 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
- 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’
- 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