Development

Notes for contributors and maintainers. End-user usage is documented in the Guides.

Why

This project exists because the official SDK and documentation were not meeting day-to-day needs. Common tasks felt harder than they should be: the API surface was inconsistent, error handling was unclear, and examples rarely matched real workflows. Fatoora started as an effort to build a clean, predictable SDK with solid defaults, thorough tests, and bindings that behave the same across languages.

We prioritize: - A small, well-typed core API with explicit errors. - A stable FFI layer for bindings and long-term compatibility. - Docs and examples that reflect the actual behavior, not just happy paths.

Quick Start

There are two main ways to use fatoora-rs: - CLI: Best for quick validation, local workflows, and CI scripts. See the Guides for install and usage examples. - Library: Use the Rust crate directly, or use language bindings that wrap the shared FFI. This is the right choice for integrating into applications or services.

Build the FFI shared library

cargo build -p fatoora-ffi --release

The compiled library will be in target/release/ for your platform (e.g. libfatoora_ffi.so, libfatoora_ffi.dylib, or fatoora_ffi.dll).

Regenerate C headers

cargo build -p fatoora-ffi --release

Headers are generated by cbindgen and written to fatoora-ffi/include/ during the build. Do not edit them manually. fatoora_ffi.h uses the fatoora_ prefix; fatoora.h provides alias names without the prefix when compiled with -DFATOORA_FFI_NO_PREFIX.

FFI workflow

Use this flow for any new public capability: 1. Add or change the Rust API in fatoora-core. 2. Expose it in fatoora-ffi (prefer the macros in fatoora-ffi/src/macros.rs). 3. Regenerate headers (see above). 4. Update language bindings (Python, C/C++) to wrap the new symbols. 5. Add or update binding tests.

FFI conventions: - Use opaque handles and *_free functions for ownership. - Return FfiResult<T> everywhere and map errors via FfiErrorKind.

API audit

See docs/development/api-audit.md for the current core/FFI surface, proposed shape, and issues to address.

Python bindings (uv)

uv venv
uv pip install -e bindings/python

Build a Python wheel (uv)

uv build --wheel

Tests

uv pip install -e bindings/python[dev]
uv run -c "import fatoora"