polyglot-ffi 0.5.1

Automatic FFI bindings generator for polyglot projects

Polyglot FFI

Automatic FFI bindings generator for polyglot projects

Stop writing FFI boilerplate. Start building amazing things.

Full Documentation | Quickstart | API Reference | Type Mapping

What is Polyglot FFI?

Polyglot FFI automatically generates complete Foreign Function Interface (FFI) bindings between programming languages. Write your OCaml interface once, and get type-safe, memory-safe bindings for Python (and soon Rust, Go, etc.) instantly.

The Problem

Building multi-language projects requires writing:

• 50+ lines of OCaml ctypes boilerplate
• 30+ lines of C stubs with tricky memory management
• 20+ lines of Python ctypes configuration
• Plus: Dune configs, debugging, memory leaks...

The Solution

polyglot-ffi generate crypto.mli

Done! All 100+ lines generated automatically.

Why Polyglot FFI?

Zero Boilerplate - One command generates OCaml ctypes declarations, C wrappers, Python modules, build configs, type conversions, and error handling.

Type Safe - Preserves type information with Python type hints, OCaml type constraints, C type declarations, and compile-time checking.

Memory Safe - Proper memory management with CAMLparam/CAMLreturn macros, no memory leaks, and GC-safe conversions.

Quick Start

Initialize a new project:

polyglot-ffi init my-crypto-lib
cd my-crypto-lib

Note on project names: You can use hyphens in project names (like my-crypto-lib). The tool automatically converts them to underscores for generated code to ensure compatibility with OCaml, C, and Python naming requirements.

Write your OCaml interface:

(* src/my-crypto-lib.mli *)
val greet : string -> string
val add : int -> int -> int

Generate bindings:

polyglot-ffi generate src/my-crypto-lib.mli

Implement your OCaml functions:

(* src/my-crypto-lib.ml *)
let greet name = "Hello, " ^ name ^ "!"
let add x y = x + y

let () =
  Callback.register "greet" greet;
  Callback.register "add" add

Use from Python:

from generated.my_crypto_lib_py import greet, add

print(greet("World"))  # Hello, World!
print(add(2, 3))       # 5

Complex types supported: Records, variants (Result, Option), lists, tuples, and more. See the Type Mapping docs for details.

Installation

pip install polyglot-ffi

Verify installation:

polyglot-ffi --version

To upgrade:

pip install --upgrade polyglot-ffi

See the full installation guide for virtual environments, shell completion, and troubleshooting.

Prerequisites for Building Generated Bindings

If you want to build and use the generated OCaml bindings (not just generate them), you'll need:

# Install OCaml and required libraries
opam install dune ctypes ctypes-foreign

Note: polyglot-ffi itself is a Python tool and doesn't require OCaml. OCaml dependencies are only needed if you want to compile the generated bindings.

Features

• Automatic Code Generation - One command generates OCaml ctypes, C wrappers, Python modules, and build configs
• Rich Type Support - Primitives, records, variants (Result, Option), lists, tuples, and nested types
• Type Safety - Full Python type hints and OCaml type preservation
• Memory Safety - Proper GC integration, no memory leaks
• Watch Mode - Auto-regenerate bindings on file changes
• Project Validation - Built-in dependency and configuration checking
• Zero Runtime Overhead - All generation happens at build time

Roadmap

• Rust target support
• Go target support
• Bidirectional bindings (call Python from OCaml)
• Plugin system for custom type mappings

Use Cases

• Cryptography - OCaml for correctness, Python for integration
• Data Processing - OCaml for logic, Python for data science
• Financial Systems - OCaml for algorithms, Python for reporting
• ML Infrastructure - OCaml for pipelines, Python for training

CLI Reference

polyglot-ffi init my-project              # Initialize new project
polyglot-ffi generate src/module.mli      # Generate bindings
polyglot-ffi watch                        # Auto-regenerate on changes
polyglot-ffi check                        # Validate configuration
polyglot-ffi clean                        # Remove generated files
polyglot-ffi --help                       # Get help

Run any command with --help for full options. See the CLI documentation for detailed usage.

Documentation

• Quickstart Guide - Get started in 5 minutes
• Type Mapping - Complete type system reference
• Architecture - How it works under the hood
• Installation Guide - Detailed setup instructions
• Contributing - Join development

Contributing & Community

We welcome contributions! See CONTRIBUTING.md for development setup, testing requirements, and PR process. Look for good-first-issue labels to get started.

Get in touch:

• GitHub: chizy7/polyglot-ffi
• Issues: Report bugs or request features
• Email: [e-mail]
• Twitter: @Chizyization

License

MIT License - See LICENSE for details.

Acknowledgments

Built with inspiration from PyO3, OCaml-Ctypes, and SWIG.