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.
This commit is contained in:
@@ -0,0 +1,68 @@
|
||||
# Wickra — C / C++ examples
|
||||
|
||||
The Wickra C ABI is a single shared/static library plus a generated header
|
||||
([`bindings/c/include/wickra.h`](../../bindings/c/include/wickra.h)). Any
|
||||
C-capable language links against the same artifact; these examples show the
|
||||
plain-C path.
|
||||
|
||||
## Build the library
|
||||
|
||||
From the workspace root:
|
||||
|
||||
```sh
|
||||
cargo build -p wickra-c --release
|
||||
```
|
||||
|
||||
This produces, in `target/release/`:
|
||||
|
||||
| Platform | Shared library | Link target |
|
||||
|----------|----------------|-------------|
|
||||
| Linux | `libwickra.so` | `-lwickra` |
|
||||
| macOS | `libwickra.dylib` | `-lwickra` |
|
||||
| Windows (MSVC) | `wickra.dll` | `wickra.dll.lib` (import lib) |
|
||||
|
||||
A static library (`libwickra.a` / `wickra.lib`) is emitted alongside.
|
||||
|
||||
## Build and run the smoke example
|
||||
|
||||
### With CMake (portable, used by CI)
|
||||
|
||||
```sh
|
||||
cmake -S examples/c -B examples/c/build -DWICKRA_LIB_DIR="$PWD/target/release"
|
||||
cmake --build examples/c/build
|
||||
ctest --test-dir examples/c/build --output-on-failure
|
||||
```
|
||||
|
||||
### Directly with a compiler
|
||||
|
||||
```sh
|
||||
# Linux / macOS
|
||||
cc examples/c/smoke.c -I bindings/c/include -L target/release -lwickra -lm -o smoke
|
||||
LD_LIBRARY_PATH=target/release ./smoke # macOS: DYLD_LIBRARY_PATH
|
||||
|
||||
# Windows (MinGW gcc, linking the DLL directly)
|
||||
gcc examples/c/smoke.c -I bindings/c/include target/release/wickra.dll -lm -o smoke.exe
|
||||
```
|
||||
|
||||
Expected output:
|
||||
|
||||
```
|
||||
OK: wickra C ABI smoke passed (SMA streaming + batch + reset + NULL-safety + free)
|
||||
```
|
||||
|
||||
## Usage shape
|
||||
|
||||
Every indicator follows the same five-function pattern over an opaque handle:
|
||||
|
||||
```c
|
||||
#include "wickra.h"
|
||||
|
||||
struct Sma *sma = wickra_sma_new(14); /* NULL on invalid params */
|
||||
double v = wickra_sma_update(sma, 42.0); /* NaN during warmup */
|
||||
wickra_sma_reset(sma); /* back to fresh state */
|
||||
wickra_sma_free(sma); /* exactly once per _new */
|
||||
```
|
||||
|
||||
There is no RAII across the C boundary: every `wickra_<ind>_new` must be paired
|
||||
with exactly one `wickra_<ind>_free`. All functions are NULL-safe (a NULL handle
|
||||
yields `NaN` / a no-op, never a crash).
|
||||
Reference in New Issue
Block a user