chore: establish project layout

2026-07-29 14:30:43 +08:00
commit 295ad2244b
14 changed files with 176 additions and 0 deletions
@@ -0,0 +1,43 @@
+# 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 write header files manually (actually performed as AI prompt and let AI do it).
+- A document instructs how to map Rust specific struct like `Option`, `Result` and etc to C-friendly FFI interface.
+
+## 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.