kingchencandGitHub
91e05e3c26
## 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.
60 lines
2.2 KiB
Markdown
60 lines
2.2 KiB
Markdown
# wickra-c
|
|
|
|
C ABI for [Wickra](https://github.com/wickra-lib/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
|
|
|
|
```sh
|
|
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`](include/wickra.h) — generated by cbindgen, committed.
|
|
|
|
## API shape
|
|
|
|
Each indicator is exposed as five `extern "C"` functions over an opaque handle:
|
|
|
|
```c
|
|
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:
|
|
|
|
```sh
|
|
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`](../../examples/c).
|
|
|
|
## License
|
|
|
|
`MIT OR Apache-2.0`, the same as the rest of Wickra.
|