blob: ce52aca3e3c0c8ea6ae35a1d5a2c9efa322c091c [file] [view]
# 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`.