#ffi #code-generation #bindings

interoptopus

The polyglot bindings generator for your library (C#, C, Python, …). 🐙

47 releases (12 breaking)

new 0.13.3 Oct 11, 2021
0.12.2 Oct 9, 2021
0.5.2 Jul 30, 2021

#31 in FFI

Download history 65/week @ 2021-06-25 93/week @ 2021-07-02 9/week @ 2021-07-09 49/week @ 2021-07-16 77/week @ 2021-07-23 162/week @ 2021-07-30 105/week @ 2021-08-06 152/week @ 2021-08-13 57/week @ 2021-08-20 26/week @ 2021-08-27 45/week @ 2021-09-03 31/week @ 2021-09-10 45/week @ 2021-09-17 92/week @ 2021-09-24 160/week @ 2021-10-01 313/week @ 2021-10-08

368 downloads per month
Used in 5 crates

MIT license

125KB
2K SLoC

Latest Version docs MIT Rust Rust

Interoptopus 🐙

The polyglot bindings generator for your library.

Interoptopus allows you to deliver high-quality system libraries to your users, and enables your users to easily consume those libraries from the language of their choice:

  • Design a single .dll / .so in Rust, consume it from any language.
  • Use patterns (e.g., classes, strings) in languages that have them.
  • Always be fully C compatible.
  • Painless workflow, no external tools required.

We strive to make our generated bindings zero cost. They should be as idiomatic as you could have reasonably written them yourself, but never magic or hiding the interface you actually wanted to expose.

Code you write ...

use interoptopus::{ffi_function, ffi_type, inventory};

#[ffi_type]
#[repr(C)]
pub struct Vec2 {
    pub x: f32,
    pub y: f32,
}

#[ffi_function]
#[no_mangle]
pub extern "C" fn my_function(input: Vec2) {
    println!("{}", input.x);
}

// This defines our FFI interface as `ffi_inventory` containing
// no constants, a single function `my_function`, no additional
// types (types are usually inferred) and no codegen patterns.
inventory!(ffi_inventory, [], [my_function], [], []);

... Interoptopus generates

Language Crate Sample Output
C# interoptopus_backend_csharp Interop.cs
C interoptopus_backend_c my_header.h
Python interoptopus_backend_cpython reference.py
Other Write your own backend1 -

1 Create your own backend in just a few hours. No pull request needed. Pinkie promise.

Getting Started 🍼

If you want to ...

Supported Rust Constructs

See the reference project for an overview:

  • functions (extern "C" functions and delegates)
  • types (composites, enums, opaques, references, ...)
  • constants (primitive constants; results of const evaluation)
  • patterns (ASCII pointers, options, slices, classes, ...)

Performance 🏁

Generated low-level bindings are zero cost w.r.t. hand-crafted bindings for that language.

That said, even hand-crafted bindings encounter some target-specific overhead at the FFI boundary (e.g., marshalling or pinning in managed languages). For C# that cost is often nanoseconds, for Python CFFI it can be microseconds.

While ultimately there is nothing you can do about a language's FFI performance, being aware of call costs can help you design better APIs.

Detailed call cost tables can be found here: 🔥

For a quick overview, this table lists the most common call types in ns / call:

Construct C# Python
primitive_void() 7 272
primitive_u32(0) 8 392
many_args_5(0, 0, 0, 0, 0) 10 786
callback(x => x, 0) 43 1168

Feature Flags

Gated behind feature flags, these enable:

  • derive - Proc macros such as ffi_type, ...
  • serde - Serde attributes on internal types.
  • log - Invoke log on FFI errors.

Changelog

  • v0.13 - Python backend uses ctypes now.
  • v0.12 - Better compat using #[ffi_service_method].
  • v0.11 - C# switch ctors to static methods.
  • v0.10 - C# flavors DotNet and Unity (incl. Burst).
  • v0.9 - 150x faster C# slices, Python type hints.
  • v0.8 - Moved testing functions to respective backends.
  • v0.7 - Make patterns proc macros for better FFI docs.
  • v0.6 - Renamed and clarified many patterns.
  • v0.5 - More ergonomic slice usage in Rust and FFI.
  • v0.4 - Enable logging support in auto-generated FFI calls.
  • v0.3 - Better compatibility with generics.
  • v0.2 - Introduced "patterns"; working interop for C#.
  • v0.1 - First version.

Also see our upgrade instructions.

FAQ

Contributing

PRs are welcome.

  • Submit small bug fixes directly. Major changes should be issues first.
  • Anything that makes previously working bindings change behavior or stop compiling is a major change;
  • This doesn't mean we're opposed to breaking stuff just that we'd like to talk about it before it happens.
  • New features or patterns must be materialized in the reference project and accompanied by an interop test (i.e., a backend test running C# / Python against a DLL invoking that code) in at least one included backend.

Dependencies

~0–265KB