# libwai, WAI's C library

WAI's C interface for Linux, as a static library:

| path | what |
|---|---|
| `include/wai.h` | the header, generated from the C interface of `wai/wai-rs` and committed there |
| `lib/libwai.a` | the library, built from `wai/wai-rs` with the feature `native_sink` |
| `lib/pkgconfig/wai.pc` | the pkg-config file: the flags to compile against the header and link the library |

## Link

```
export PKG_CONFIG_PATH=/path/to/this/directory/lib/pkgconfig
cc your-program.c $(pkg-config --cflags --libs wai) -o your-program
```

`wai.pc` finds its own directory, so this directory can be unpacked anywhere. The library is
static: the program carries it, and nothing of libwai is looked for when the program runs. It is
built for this archive's glibc target without a static C runtime, so the program uses the C
library it is linked against. `pkg-config --libs wai` names the system libraries libwai needs
beside `-lwai`.

## What it holds

The envelope and the native sink: `wai_envelope_pack`, `wai_envelope_unpack`,
`wai_envelope_detect_version`, `wai_envelope_pack_multi`, `wai_envelope_unpack_multi`,
`wai_envelope_select`, `wai_int_payload_declared`, `wai_buffer_free`, `wai_last_error`, every
`wai_sink_*` function (extensions/native-sink.md §9) and `wai_audit_verify_bundle`. It is the
interface the Swift package's `WaiFFI.xcframework` and the Android library carry, and it needs no
library but the C runtime.

`wai.h` also declares the codec wrappers (`wai_image_*`, `wai_audio_*`, `wai_text_*`,
`wai_video_*`) and the neural decoders (`wai_neural_*`). They need codec and model libraries, and
they are not in this library: a program that calls one of them does not link.

A call that can fail returns a status, 0 for success, and `wai_last_error()` says why it failed;
a buffer a call writes is freed with `wai_buffer_free`. The header's comments state each
function's contract.