rotr

Universal FFI binding generator. Parses C headers, infers ownership/nullability/error semantics via heuristics, and generates idiomatic bindings for 6 languages from a single annotated manifest.

C Headers → rotr annotate → .rotr manifest → rotr generate → Python | Rust | Go | Node.js | Java | C#

Quick Start

# Build
odin build src/ -out:rotr

# Parse a C header
rotr parse widget.h

# Generate annotation manifest with heuristic inference
rotr annotate widget.h -o rotr.toml

# Edit rotr.toml to refine ownership/nullability annotations, then generate bindings
rotr generate rotr.toml -t python -o bindings/
rotr generate rotr.toml -t rust -o bindings/
rotr generate rotr.toml --all-targets -o bindings/

# Check for header drift
rotr check rotr.toml
rotr diff rotr.toml

What It Does

C headers are an incomplete specification — they encode types but omit ownership, nullability, error conventions, and lifetime relationships. Every FFI binding fills those gaps manually. rotr centralizes that knowledge in a .rotr annotation manifest and generates correct bindings for all targets simultaneously.

Heuristic inference detects common patterns automatically:

*_create / *_destroy pairs → caller_frees ownership
const char* returns → borrowed
*_find / *_get → nullable return
int return + action name → negative_on_error
Error enums with *_OK → error type detection

Generated bindings are idiomatic, not transliterated:

Language	Ownership Pattern	Error Handling
Python	Context managers (`with`)	Exception translation
Rust	`Drop` impl, `Result<T,E>`	`Option<T>` for nullable
Go	`runtime.SetFinalizer`	`(value, error)` returns
Node.js	N-API ref-counted externals	`napi_throw_error`
Java	`AutoCloseable`	`RuntimeException`
C#	`SafeHandle` + `IDisposable`	Exception translation

Commands

Command	Description
`rotr parse <headers>`	Parse C headers, show declarations
`rotr annotate <headers>`	Infer annotations, emit `.rotr` manifest
`rotr generate <manifest>`	Generate bindings from manifest
`rotr check <manifest>`	Validate manifest against current headers
`rotr diff <manifest>`	Show what changed since last annotation

Testing

# Compile test C library
cc -shared -o /tmp/libwidget.dylib testdata/widget_impl.c -fPIC

# Run full test suite (26 tests)
bash testdata/test_all.sh

# Run integration test (calls real C library from Python)
python3 testdata/test_integration.py

Requirements

Odin dev-2026-03 or later
For testing: Python 3, Go (gofmt), Rust (rustc)

License

MIT