From d7e564d666005477dabbc46b665f1c1f4ba68508 Mon Sep 17 00:00:00 2001 From: yyc12345 Date: Tue, 11 Aug 2026 22:47:50 +0800 Subject: [PATCH] refactor: refactor ffi design document --- assets/c-friendly-ffi-design/c-cpp-side.md | 1 + .../c-header.md} | 2 +- .../c-cpp-side/cpp-header.md | 3 ++ .../c-cpp-side/example.md | 15 ++++++++++ .../c-friendly-ffi-design/c-cpp-side/misc.md | 1 + assets/c-friendly-ffi-design/index.md | 14 +++++++-- assets/c-friendly-ffi-design/packer.md | 2 ++ assets/c-friendly-ffi-design/rust-side.md | 4 +++ .../data-types.md} | 0 .../rust-side/example.md | 15 ++++++++++ .../func-signature.md} | 30 +++++++++---------- .../c-friendly-ffi-design/rust-side/misc.md | 1 + 12 files changed, 69 insertions(+), 19 deletions(-) create mode 100644 assets/c-friendly-ffi-design/c-cpp-side.md rename assets/c-friendly-ffi-design/{c-cpp-headers.md => c-cpp-side/c-header.md} (99%) create mode 100644 assets/c-friendly-ffi-design/c-cpp-side/cpp-header.md create mode 100644 assets/c-friendly-ffi-design/c-cpp-side/example.md create mode 100644 assets/c-friendly-ffi-design/c-cpp-side/misc.md create mode 100644 assets/c-friendly-ffi-design/packer.md create mode 100644 assets/c-friendly-ffi-design/rust-side.md rename assets/c-friendly-ffi-design/{allowed-data-types.md => rust-side/data-types.md} (100%) create mode 100644 assets/c-friendly-ffi-design/rust-side/example.md rename assets/c-friendly-ffi-design/{ffi-function-signatures.md => rust-side/func-signature.md} (89%) create mode 100644 assets/c-friendly-ffi-design/rust-side/misc.md diff --git a/assets/c-friendly-ffi-design/c-cpp-side.md b/assets/c-friendly-ffi-design/c-cpp-side.md new file mode 100644 index 0000000..960e794 --- /dev/null +++ b/assets/c-friendly-ffi-design/c-cpp-side.md @@ -0,0 +1 @@ +# C/C++ Side diff --git a/assets/c-friendly-ffi-design/c-cpp-headers.md b/assets/c-friendly-ffi-design/c-cpp-side/c-header.md similarity index 99% rename from assets/c-friendly-ffi-design/c-cpp-headers.md rename to assets/c-friendly-ffi-design/c-cpp-side/c-header.md index 1fd575d..093cf95 100644 --- a/assets/c-friendly-ffi-design/c-cpp-headers.md +++ b/assets/c-friendly-ffi-design/c-cpp-side/c-header.md @@ -1,4 +1,4 @@ -# C/C++ Headers +# C Header Under this section we discuss how to write the C/C++ header files that accompany the Rust FFI library. The Rust-side counterpart of each topic is covered in diff --git a/assets/c-friendly-ffi-design/c-cpp-side/cpp-header.md b/assets/c-friendly-ffi-design/c-cpp-side/cpp-header.md new file mode 100644 index 0000000..240e6d5 --- /dev/null +++ b/assets/c-friendly-ffi-design/c-cpp-side/cpp-header.md @@ -0,0 +1,3 @@ +# C++ Header + + diff --git a/assets/c-friendly-ffi-design/c-cpp-side/example.md b/assets/c-friendly-ffi-design/c-cpp-side/example.md new file mode 100644 index 0000000..2389a74 --- /dev/null +++ b/assets/c-friendly-ffi-design/c-cpp-side/example.md @@ -0,0 +1,15 @@ +# C/C++ Headers Example + + + +## C Header Example + +```c + +``` + +## C++ Header Example + +```c++ + +``` diff --git a/assets/c-friendly-ffi-design/c-cpp-side/misc.md b/assets/c-friendly-ffi-design/c-cpp-side/misc.md new file mode 100644 index 0000000..8416470 --- /dev/null +++ b/assets/c-friendly-ffi-design/c-cpp-side/misc.md @@ -0,0 +1 @@ +# Miscellaneous Stuff diff --git a/assets/c-friendly-ffi-design/index.md b/assets/c-friendly-ffi-design/index.md index cfe6cb1..28a2a12 100644 --- a/assets/c-friendly-ffi-design/index.md +++ b/assets/c-friendly-ffi-design/index.md @@ -8,6 +8,14 @@ to write the accompanying C/C++ header files. ## Contents -- [FFI Function Signatures](ffi-function-signatures.md) -- [Allowed Data Types](allowed-data-types.md) -- [C/C++ Headers](c-cpp-headers.md) +* [Rust Side](rust-side.md) + - [FFI Function Signature](rust-side/func-signature.md) + - [Allowed Data Types](rust-side/data-types.md) + - [FFI Example](rust-side/example.md) + - [Miscellaneous Stuff](rust-side/misc.md) +* [C/C++ Side](c-cpp-side.md) + - [C Header](c-cpp-side/c-header.md) + - [C++ Header](c-cpp-side/cpp-header.md) + - [C/C++ Headers Example](c-cpp-side/example.md) + - [Miscellaneous Stuff](c-cpp-side/misc.md) +* [Pack Distribution](packer.md) diff --git a/assets/c-friendly-ffi-design/packer.md b/assets/c-friendly-ffi-design/packer.md new file mode 100644 index 0000000..bba5a50 --- /dev/null +++ b/assets/c-friendly-ffi-design/packer.md @@ -0,0 +1,2 @@ +# Pack Distribution + diff --git a/assets/c-friendly-ffi-design/rust-side.md b/assets/c-friendly-ffi-design/rust-side.md new file mode 100644 index 0000000..97c93e0 --- /dev/null +++ b/assets/c-friendly-ffi-design/rust-side.md @@ -0,0 +1,4 @@ +# Rust Side + + + diff --git a/assets/c-friendly-ffi-design/allowed-data-types.md b/assets/c-friendly-ffi-design/rust-side/data-types.md similarity index 100% rename from assets/c-friendly-ffi-design/allowed-data-types.md rename to assets/c-friendly-ffi-design/rust-side/data-types.md diff --git a/assets/c-friendly-ffi-design/rust-side/example.md b/assets/c-friendly-ffi-design/rust-side/example.md new file mode 100644 index 0000000..6388779 --- /dev/null +++ b/assets/c-friendly-ffi-design/rust-side/example.md @@ -0,0 +1,15 @@ +# FFI Example + + + +## Rust Core Crate + +```rust + +``` + +## Rust FFI Binding Crate + +```rust + +``` diff --git a/assets/c-friendly-ffi-design/ffi-function-signatures.md b/assets/c-friendly-ffi-design/rust-side/func-signature.md similarity index 89% rename from assets/c-friendly-ffi-design/ffi-function-signatures.md rename to assets/c-friendly-ffi-design/rust-side/func-signature.md index cb83ad3..0d65e6d 100644 --- a/assets/c-friendly-ffi-design/ffi-function-signatures.md +++ b/assets/c-friendly-ffi-design/rust-side/func-signature.md @@ -1,15 +1,15 @@ -# FFI Function Signatures +# FFI Function Signature Under this section we discuss the signature requirements of the exported FFI functions. -## C-style Name Export +## The Way of Exporting Function FFI functions must be exported under C names, that is, they must not go through the C++ name mangling mechanism. -In Rust, you need to decorate the function with the `#[unsafe(no_mangle)]` attribute -together with `extern "C"`, for example: +This requirement means that, in Rust, you need to decorate the function with the +`#[unsafe(no_mangle)]` attribute together with `extern "C"`, for example: ```rust #[unsafe(no_mangle)] @@ -20,7 +20,7 @@ pub extern "C" fn WFStartup() -> CError { // More FFI functions omitted... ``` -## Export Name Style +## Function Name Styles In this subsection, we discuss the naming style of exported functions. @@ -93,10 +93,11 @@ The following examples show some legal and illegal POSIX style function names: | `wf_GetMessage` | Illegal | ``, which is `GetMessage`, is not snake_case. | | `wf_Icon_get_message` | Illegal | ``, which is `Icon`, is not snake_case. | -## Parameters and Return Value +## Function Signature Rules -Under this section we discuss the parameters and return value of the exported -functions. A standard FFI function looks like the following on the Rust side: +Under this subsection we discuss the parameters and return value of the exported +functions. A standard FFI function following this design looks like the following +on the Rust side: ```rust #[unsafe(no_mangle)] @@ -160,10 +161,9 @@ absolute, unambiguous success. Every other value's meaning is decided by the consuming project: it may denote a failure, or, like some Win32 functions, a partial success. -#### Migrating from a bool Return Value - -Projects that previously returned a plain `bool` can adopt the error-code scheme -with minimal change: define exactly one non-success code, for example -`const CERROR_FAIL: CError = 1;`, and map every error type to it. The result is -equivalent to a `bool`: `CERROR_OK` for success and `CERROR_FAIL` for any failure, -while leaving room to introduce finer-grained codes later. +> [!TIP] +> Projects that previously returned a plain `bool` can adopt the error-code scheme +> with minimal change: define exactly one non-success code, for example +> `const CERROR_FAIL: CError = 1;`, and map every error type to it. The result is +> equivalent to a `bool`: `CERROR_OK` for success and `CERROR_FAIL` for any failure, +> while leaving room to introduce finer-grained codes later. diff --git a/assets/c-friendly-ffi-design/rust-side/misc.md b/assets/c-friendly-ffi-design/rust-side/misc.md new file mode 100644 index 0000000..8416470 --- /dev/null +++ b/assets/c-friendly-ffi-design/rust-side/misc.md @@ -0,0 +1 @@ +# Miscellaneous Stuff