| # Replacing one of two mutually-recursive C++ functions with Rust | |
| This directory shows how to rewrite a single function of a `cc_library` in Rust | |
| when that function and another C++ function in the same library call each other. | |
| `parity.h` declares two functions, `parity::IsEven` and `parity::IsOdd`, each of | |
| which calls the other: | |
| * `IsEven` is still implemented in C++, in `parity.cc`. | |
| * `IsOdd` is now implemented in Rust, as `is_odd::is_odd` in `is_odd.rs`, | |
| which calls `IsEven` through Crubit's Rust bindings for `parity.h`. | |
| * `parity.cc` keeps a one-line C++ definition of `parity::IsOdd` that calls | |
| `is_odd::is_odd` through Crubit's C++ API for the Rust crate | |
| (`cpp_api_from_rust`, `is_odd.h`). The C++ API and ABI of `parity::IsOdd` | |
| don't change, and neither do its callers. | |
| ## Breaking the dependency cycle | |
| `:parity` depends on `:is_odd` (through `:is_odd_cc`), because `parity.cc` calls | |
| `is_odd::is_odd`. `:is_odd` can't depend on `:parity` in return, because Bazel | |
| doesn't allow dependency cycles. Instead, `:is_odd` gets its bindings for | |
| `IsEven` from `:parity_decls`, a `cc_library` with the same header (`parity.h`) | |
| but no `srcs`: | |
| ``` | |
| :parity ──> :is_odd_cc ──> :is_odd ──> :parity_decls_rust ──> :parity_decls | |
| │ ▲ | |
| └───────────────────────────────────────────────────────────────┘ | |
| ``` | |
| The definition of `IsEven` still comes from `:parity`, so every binary that uses | |
| `:is_odd` must also depend on `:parity` (see `main_rs` in the `BUILD` file). C++ | |
| binaries depend on `:parity` anyway. | |
| ## `alwayslink = True` | |
| The functions still refer to each other at link time, even though the Bazel | |
| targets don't. Bazel puts each library on the link line before the libraries it | |
| depends on, so `:parity` comes before `:is_odd`. The linker only pulls a | |
| library's object files into the link when an earlier file refers to one of their | |
| symbols. If nothing has pulled in `parity.cc` by the time the linker reaches | |
| `:is_odd`, for example in a Rust binary that only calls `is_odd::is_odd`, then | |
| `:is_odd`'s reference to `IsEven` points backwards. lld resolves backward | |
| references (traditional Unix linkers don't), but with `--warn-backrefs` (which | |
| many toolchains enable, to catch link-order bugs) they are an error: | |
| ``` | |
| ld: error: backward reference detected: _ZN6parity6IsEvenEi in | |
| .../libis_odd-<hash>.a(...) refers to .../_objs/parity/parity.pic.o | |
| ``` | |
| Setting `alwayslink = True` on `:parity` makes the linker always include | |
| `parity.cc`, so `IsEven` is already defined when the linker reaches `:is_odd`. | |
| No linker flags are needed. | |
| ## Alternatives | |
| * If none of the C++ code in the library needs to call the Rust function, no | |
| cycle exists: put the Rust function in a separate `rust_library`, and call | |
| it from C++ through `cpp_api_from_rust`. | |
| * To move a whole library to Rust at once, see `examples/cpp/carcinize`. |