ezffi-macros 0.1.1

Proc-macros backing the ezffi crate
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

# ezffi

Generate idiomatic C-FFI bindings from Rust types and functions with a single attribute, without having to worry about whether your types use C-compatible fields or not.

```rust
#[ezffi::export]
pub struct Car { km: u64 }

#[ezffi::export]
impl Car {
    pub fn new() -> Self { Self { km: 0 } }
    pub fn drive(&mut self, km: u64) { self.km += km; }
    pub fn km(&self) -> u64 { self.km }
}
```

Pair it with cbindgen and you get:

```c
typedef struct MyCrateCar { uint64_t km; } MyCrateCar;

MyCrateCar my_crate_car_new(void);
void       my_crate_car_drive(MyCrateCar *this_, uint64_t km);
uint64_t   my_crate_car_km(const MyCrateCar *this_);
```

## Ideas

- **One attribute.** `#[ezffi::export]` on structs, enums, `impl` blocks emits the C wrappers, the type definitions, and  the `free` function. No `#[repr(C)]` needed.
- **Picks the layout for you.** Types whose fields are all C-compatible cross the boundary as `#[repr(C)]` values; everything else goes behind an opaque pointer struct. The macro reads the source, no annotations — `ezffi` always makes the right decision.
- **Honest C signatures.** `&self` → `const T*`, `&mut self` → `T*`, owned `T` → `T` by value. The C side actually reflects which calls mutate (with a few exceptions for performance reasons).
- **Built-ins ship with their own headers.** `Option`, `Result`, `String`, and (with `std`) `Vec`, `HashMap`, `Arc`, `BTreeMap`, etc., come pre-wrapped, each in its own `ezffi/…h`, so the consumer `#include`s only what they touch. This lets you export almost any function you write in Rust without having to worry about type compatibility.
- **Cross-crate aware.** A crate can take a type another `ezffi` crate exports and the macro resolves it without re-declaration.

## Quick start and Documentation

📖 **[The ezffi Book](https://zocolini.github.io/ezffi/)** contains all the information you need to set up and use this crate. It also explains how `ezffi` works internally and how to correctly use all the features it ships. It'll definitely help you decide if this crate is the right tool for your work.

Right now the book tracks the `master` branch only, I'll eventually set up per-version hosting so users can read the docs that match their installed version.

For examples, look at the crates under [`ffi-c-tests/`](ffi-c-tests/), I'll be adding proper example files that are more readable than the test ones.

## Features

- `std` — bundles wrappers for `Vec`, `HashMap`, `BTreeMap`, `HashSet`, `BTreeSet`, `Arc`, `Rc`, `VecDeque`. Off by default. I'll keep adding more if I see it's needed so users can `#[ezffi::export]` everything they need. See the [book](https://zocolini.github.io/ezffi/std-library.html#rust-std-library) for more.
- `async` — lets you export async functions and plug in your own async dispatcher, see the [book](https://zocolini.github.io/ezffi/the-macro.html#async-functions) for more.