Theus is a procedural macro. It will run at compile time and transform your program's source code.

Adding `theus` macro(s) as a dependency

Run this command in a terminal, in your project's directory:

cargo add theus

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

theus = "0.1.1"

You may need to import the macro(s) with use theus::*.

Read the theus documentation.

Back to the crate overview.

Readme

theus

Welding Rust to other languages. Theus is a procedural macro for seamlessly generating C-compatible functions from Rust structs and traits.

Features

Automatically generates C-compatible wrapper functions for Rust struct methods and trait implementations.
Handles both regular impl Struct blocks and impl Trait for Struct blocks.
Preserves doc comments from Rust functions in the generated C-compatible functions (useful for passing doc comments to tools like cbindgen for later use).
Enforces the use of &mut self instead of &self for all methods (never know what external code will do with your pointers)
Wraps all non-scalar and non-pointer types in pointers for safe passing across the FFI boundary
Allows direct passing of scalar types, without wrapping them in pointers

Usage

Add this to your Cargo.toml:

[dependencies]
theus = "0.1.0"

Then, in your Rust code:

use theus::c_compatible;

struct MyStruct {
    value: i32,
}

#[c_compatible]
impl MyStruct {
    pub fn create(value: i32) -> Self {
        MyStruct { value }
    }

    pub fn get_value(&mut self) -> i32 {
        self.value
    }

    // Note the owned receiver. The struct
    // will be dropped by the borrow checker
    // once this function finishes execution
    pub fn destroy(self) {}
}

trait MyTrait {
    fn trait_method(&mut self, x: i32) -> i32;
}

#[c_compatible]
impl MyTrait for MyStruct {
    fn trait_method(&mut self, x: i32) -> i32 {
        self.value + x
    }
}

Theus will generate the following code at compile time. When you compile this to a cdylib, it can be used with any C-compatible interface.

#[no_mangle]
pub unsafe extern "C" fn mystruct_create() -> *mut MyStruct {
    Box::into_raw(Box::new(MyStruct::create()))
}

#[no_mangle]
pub extern "C" fn mystruct_get_value(ptr: *mut MyStruct) -> i32 {
    (unsafe { &mut *ptr }).get_value()
}

#[no_mangle]
pub extern "C" fn mystruct_destroy(ptr: *mut MyStruct) {
    unsafe { Box::from_raw(ptr) }.destroy()
}

#[no_mangle]
pub extern "C" fn mystruct_mytrait_trait_method(ptr: *mut MyStruct, x: i32) -> i32 {
    (unsafe { &mut *ptr }).trait_method(x)
}

Namesake

Gladys Theus (1923-2012)

Miss Gladys Theus in 1945, one of the fastest and most efficient welders at the Kaiser Company Permanente Metals Corporation yards of Richmond, California. She is sticking to her job until final victory is won.

- National Archives and Records Administration, Washington, US.

Adding theus macro(s) as a dependency

Adding `theus` macro(s) as a dependency