| Lukasz Anforowicz | dcdb524a | 2025-03-24 19:26:41 | [diff] [blame] | 1 | # Rust FFI |
| 2 | |
| 3 | This document tries to provide guidance for C++/Rust FFI. |
| 4 | CLs to improve this guidance are welcomed. |
| 5 | |
| 6 | ## General guidance |
| 7 | |
| 8 | Chromium recommends using [the `cxx` crate](https://cxx.rs/) for C++/Rust FFI. |
| 9 | For introductory guidance, please see |
| 10 | [the `cxx` chapter](https://google.github.io/comprehensive-rust/chromium/interoperability-with-cpp.html) |
| 11 | in the Chromium day of the Comprehensive Rust course. |
| 12 | |
| 13 | Chromium also supports the following tools: |
| 14 | |
| 15 | * [`bindgen`](https://rust-lang.github.io/rust-bindgen/) - see |
| 16 | `//build/rust/rust_bindgen.gni` for usage instructions. |
| 17 | |
| 18 | At this point Chromium's `//build/rust/*.gni` templates do not support other FFI |
| 19 | tools like: |
| 20 | |
| 21 | * [`cbindgen`](https://github.com/mozilla/cbindgen) |
| 22 | * [`crubit`](https://github.com/google/crubit) |
| 23 | |
| 24 | ### `cxx` guidance |
| 25 | |
| 26 | #### Best practices |
| 27 | |
| 28 | * Generate C++ side of bindings into a project-specific or crate-specific |
| 29 | `namespace`. For example: `#[cxx::bridge(namespace = "some_cpp_namespace")]`. |
| 30 | * Maintain binding declarations in a **single** `#[cxx::bridge]` declaration. |
| 31 | `cxx` supports reusing types across multiple `bridge`s, but there are some |
| 32 | rough edges. |
| 33 | |
| 34 | #### Suggestions |
| 35 | |
| 36 | TODO: Provide some examples or suggestions on how to structure FFI bindings |
| 37 | (even if these suggestions wouldn't necessarily rise to the level of "best |
| 38 | practices"). |
