aviso-ffi

A stable C ABI for aviso, the core Rust client library for aviso-server, plus a hand-written header-only C++ facade over it.

This crate is a peer consumer of the core aviso crate, like aviso-cli and the aviso-py binding crate: it depends on aviso and never the reverse, and the core carries no FFI machinery. It builds as a staticlib and a cdylib, so a C or C++ application links the prebuilt libaviso_ffi.{a,so,dylib} with its own toolchain and needs no Rust toolchain in its build.

Layout

• src/: the hand-written extern "C" surface.
• include/aviso.h: the C header, generated by cbindgen and checked in.
• include/aviso.hpp: the header-only C++ facade (RAII handles, std::string / std::optional, a throwing aviso::Error). Hand-written, not generated; it includes aviso.h.

A worked CMake consumer lives in examples/cpp.

Installing the library

cargo-c compiles the crate and installs it in the standard C layout — a .a, a versioned .so/.dylib, a pkg-config .pc, and the headers — so a C or C++ consumer then discovers it with pkg-config (or CMake's pkg_check_modules) and links it with no Rust toolchain of its own:

cargo install cargo-c   # once
cargo cinstall -p aviso-ffi --release --prefix=/usr/local --libdir=/usr/local/lib

This drops lib/libaviso_ffi.{a,so,dylib}, lib/pkgconfig/aviso_ffi.pc, and include/aviso_ffi/{aviso.h,aviso.hpp}. The committed include/aviso.h stays the header source of truth: cargo-c installs it verbatim (header generation is off), so the cbindgen drift guard below still governs the surface. just ffi-cinstall <prefix> wraps the command.

Regenerating the C header

include/aviso.h is committed and must match the extern "C" surface. After changing that surface, regenerate it:

cargo run -p aviso-ffi --features gen-header --bin gen-header

CI regenerates into a temporary file and fails if it differs from the committed header, so a surface change without a regenerate is caught.

License

Apache-2.0. See LICENSE.txt. Copyright 2026 ECMWF and individual contributors.