Files

T

kingchenc 91e05e3c26 C ABI hub crate (bindings/c) foundation (#222 )

## What

Introduces `wickra-c` — a `cdylib` + `staticlib` that exposes the Rust core over a **C ABI**. This is the hub every C-capable language (C, C++, Go, C#, Java, R) links against, instead of re-wiring each indicator natively. The native Python/Node/WASM bindings are untouched; this is purely additive, for ecosystems without first-class Rust tooling.

## Scope (foundation slice)

This PR deliberately validates the **whole pipeline end to end with one indicator (SMA)** before scaling to all 514, so the CI / cross-OS / header-drift mechanics are proven green first.

- Opaque `*mut T` handles; `wickra_<ind>_{new,update,batch,reset,free}`.
- NaN sentinel for warmup / NULL handles; caller-owned batch buffers; every function NULL-safe.
- cbindgen generates and commits `bindings/c/include/wickra.h` with opaque handle typedefs.
- A C smoke example (`examples/c/`) links the header + compiled library and runs (CMake + ctest).
- A `c-abi` CI job builds the library and runs the smoke test on **Linux, macOS and Windows**, plus a header drift check on Linux.

## Notes

- The per-indicator FFI blocks are plain `#[no_mangle]` functions, **not** a macro: cbindgen cannot see macro-generated functions on stable Rust (macro expansion needs nightly), so the blocks are written literally and will be generated mechanically by the ScriptHelpers `capi` wrapper in a follow-up (same model as the committed-but-generated Node `index.js`).
- `bindings/c` cannot inherit the workspace `forbid(unsafe_code)` lint (the C boundary needs raw pointers), so it mirrors every workspace lint and only relaxes `unsafe_code`. The Rust core stays `unsafe`-forbidden.

## Follow-ups (separate PRs)

- ScriptHelpers `capi` generator + wire the scalar family (~235).
- Hand-written blocks for multi-output / custom-input / bars (~279).
- Docs consistency wave (README / docs / webpage: Python·Node·WASM·Rust → +C).
- Release wiring (native-lib matrix + header/lib GH-release assets) — gated.

2026-06-09 02:07:03 +02:00

2.2 KiB

Raw Permalink Blame History

wickra-c

C ABI for Wickra — streaming-first technical indicators with a Rust core. This crate is the hub: it compiles the core to a C-compatible shared/static library plus a generated header, so any C-capable language (C, C++, Go, C#, Java, R) links against one artifact instead of re-wiring every indicator natively.

The native Python, Node, and WebAssembly bindings are unaffected — this is additive, for the ecosystems without first-class Rust tooling.

Artifacts

cargo build -p wickra-c --release

target/release/libwickra.{so,dylib} / wickra.dll (+ wickra.dll.lib import lib on Windows)
target/release/libwickra.a / wickra.lib (static)
include/wickra.h — generated by cbindgen, committed.

API shape

Each indicator is exposed as five extern "C" functions over an opaque handle:

struct Sma *wickra_sma_new(uintptr_t period);                 /* NULL on bad params */
double      wickra_sma_update(struct Sma *h, double value);   /* NaN during warmup */
void        wickra_sma_batch(struct Sma *h, const double *in, double *out, uintptr_t n);
void        wickra_sma_reset(struct Sma *h);
void        wickra_sma_free(struct Sma *h);                   /* exactly once per _new */

Conventions:

Opaque handles. wickra_<ind>_new returns a T * you must release with exactly one wickra_<ind>_free. There is no RAII across the boundary.
NaN sentinel. Scalar outputs return NaN while warming up or on a NULL handle, mirroring the other bindings — no error codes for the common path.
Caller-owned batch buffers. wickra_<ind>_batch writes one output per input into a buffer you provide; nothing is allocated across the boundary.
NULL-safe. Every function tolerates a NULL handle without crashing.

Header regeneration

The header is generated and committed; CI checks it is in sync:

cbindgen --config bindings/c/cbindgen.toml --crate wickra-c --output bindings/c/include/wickra.h

Examples

Runnable C examples (build via CMake or a direct compiler invocation) live in examples/c.

License

MIT OR Apache-2.0, the same as the rest of Wickra.

2.2 KiB Raw Permalink Blame History