sarasacw-omrf/README.md

# Oh My Rust FFI

Sarasas Chip Workshop Oh My Rust FFI (abbr. SarasaCW OMRF) is a toolset including following components:

- A Rust crate providing various facilities for C-friendly FFI.
- A Python written tool for creating distribution and generating CMake and pkg-config files.
- A document instructs how to design C-friendly FFI signatures and write C/C++ header files, 
involving how to pass primitive type, enum type, string and Rust specific structs like `Option`, `Result`.

## Why not XXX?

This toolset is specifically served for the Rust workflow and usage in Sarasas Chip Workshop.
Because we have browsed the most of popular Rust FFI solutions and no one fit our requirements.
So we develop it for our special requirements.

### Not `cbindgen`

`cbindgen` is a good tool but it only simply resolve only one Rust source file.
It can't handle `use` syntax and means that we need put all things into single file.
For a large-scale FFI interface, this behavior is unacceptable.

### Not `Diplomat`

Mozilla developed `Diplomat` is another great tool but it still doesn't fit our requirements.
`Diplomat` prefers integrating Rust in workflow rather than distributing Rust built artifacts.
Although `Diplomat` generated C/C++ header files can correctly process module relation and `use` syntax,
it generated header files involve too much hacks and memory layout assumption based on target triple.
This behavior causes that it generated header files only works on build machine and can not be distributed.
It violates our requirements that we want our developed Rust projects can be distributed like a normal CMake project.

Sarasas Chip Workshop developed Rust projects has no requirement that exposing complex structs like
`Option`, `Result`, `Vec`, Generic and etc.
All of these complex concepts are transformed into C-friendly pattern when exposing them.
So the feature of `Diplomat` about handling complex structs is not only not helping us, but is actually a burden to us.

### Not `cargo-c`

`cargo-c` is the tool that comes closest to what we need by configuring some essential metadatas.
But it doesn't support CMake generation. It only supports pkg-config.
Considering some of our developed projects involve MSVC-only Windows environment, this is unacceptable.

In addition, a small annoy spot is that installing `cargo-c` takes too much dependencies.
It is a little bit uncomfortable but still okey.