doc: update ffi design

2026-08-14 16:38:09 +08:00
parent d7e92d588f
commit 40fee18194
9 changed files with 144 additions and 28 deletions
@@ -1 +1,30 @@
 # Miscellaneous Stuff
+
+## Two-Project Workspace Structure
+
+When writing FFI, we require you to develop with two projects using the Rust workspace mechanism. For example:
+
+- An ordinary Rust library project named `foobar`. In this project you write your library logic in a pure Rust way.
+- An FFI-specific library project named `foobar-ffi` (the name is not mandatory). This project references `foobar` within the workspace, writes the relevant code according to this design, wraps `foobar` into a form suitable for FFI export, and finally exports it in FFI form.
+
+## Panic Policy
+
+In the FFI project, we enforce that every panic causes the process to exit immediately, just like executing `std::abort` in C++. So you need to specify the following in the Cargo.toml of the FFI project, so that this feature is enabled only in the production environment (that is, the release mode):
+
+```toml
+[profile.release]
+panic = "abort"
+```
+
+The reason for enabling this feature only in the release mode is that in the debug mode you may need to perform operations such as stack tracing to debug the project, and enabling this feature would make such operations impossible.
+
+You may think this operation would cause the user's process to crash frequently. But a well-designed library should be able to catch all recoverable errors and try not to trigger any unrecoverable errors. This operation forces developers to design a well-functioning library and eliminate potential errors during the development stage.
+
+## Artifact Type
+
+The build artifact of the FFI project should meet the requirements of the C language FFI. So you need to specify the following in the Cargo.toml of the FFI project to set the produced artifact type:
+
+```toml
+[lib]
+crate-type = ["cdylib"]
+```