Crate interoptopus[−][src]
Expand description
Interoptopus 🐙
Extensible, lightweight, convenient FFI bindings for any* language calling Rust.
Escape hatchets included. 🪓
* C#, C, Python provided. Add yours in 4 hours. No pull request needed.
Code you write …
use interoptopus::{ffi_function, ffi_type, inventory_function}; #[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); } inventory_function!(ffi_inventory, [], [my_function], []);
… Interoptopus generates
Language | Crate | Sample Output |
---|---|---|
C# (incl. Unity) | interoptopus_backend_csharp | Interop.cs |
C | interoptopus_backend_c | my_header.h |
Python CFFI | interoptopus_backend_cpython_cffi | reference.py |
Your language | Write your own backend! | - |
Getting Started 🍼
If you …
- want to create a new API see the example projects,
- need to support a new language or rewrite a backend, copy and adapt the C backend.
Features
- explicit, type-safe, single source of truth API definition in Rust,
- minimal on dependencies, build time, tooling impact
- if your project compiles your bindings should workTM, *cough* (i.e., generated and callable)
- extensible, multiple backends, easy to support new languages, or totally change existing ones
- quality-of-life patterns on both sides (e.g., options, slices, services, …)
- doesn’t need build scripts,
cargo build
+cargo test
can produce and test (if lang installed) generated bindings
Supported Rust Constructs
See the reference project; it lists all supported constructs including:
- functions (
extern "C"
functions and delegates) - types (primitives, composite, enums (numeric only), opaques, references, pointers, …)
- constants (primitive constants; results of const evaluation)
- patterns (ASCII pointers, options, slices, classes, …)
As a rule of thumb we recommend to be slightly conservative with your signatures and always “think C”, since other languages don’t track lifetimes
well and it’s is easy to accidentally pass an outlived pointer or doubly alias a &mut X
on reentrant functions.
Current Status
- June 20, 2021 - Alpha. Has generated simple workingTM bindings for a few projects for a week now, many things missing.
- June 13, 2021 - Pre-alpha. Has generated C#, C, Python-CFFI bindings at least once, many things missing, untested.
FAQ
Contributing
PRs are welcome.
-
Bug fixes can be submitted directly. Major changes should be filed as issues first.
-
Anything that would make previously working bindings change behavior or stop compiling is a major change; which doesn’t mean we’re opposed to breaking stuff before 1.0, 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.
Modules
Abstractions for authors of backends.
Optional types that translate to binding with better semantics in languages supporting them.
testing
Test generated bindings for various languages.
Helpers for backend authors.
Types used by backends to produce pretty output.
Macros
Writes a line of code, possibly with multiple indentations. Used in backends.
derive
The macro to define your library, ties everything together!
Defines a Service
pattern and generate FFI wrapper code.
Defines a Service
pattern, usually producing a class in OO languages.
Structs
Represents all FFI-relevant items, produced via inventory_function
, ingested by backends.
Enums
Can be observed if something goes wrong.
Traits
Main entry point for backends to generate language bindings.
Attribute Macros
derive
Enables a const
to appear in generated bindings.
derive
Enable an extern "C"
function to appear in generated bindings.
derive
Enable a struct
or enum
to appear in generated bindings.