Rust and C++

Rust introduces many useful features that are missing in C++. This document shows how to use them in Scylla.

Using Rust in Scylla

To create a Rust package new_pkg and use it in a C++ source file:

1. Create a new package in the rust directory using cargo new new_pkg --lib
2. Add new_pkg = { path = "new_pkg", version = "0.1.0" } to the dependencies list in rust/Cargo.toml
3. Add extern crate new_pkg; to rust/src/lib.rs
4. Configure your package in new_pkg/Cargo.toml and write your Rust code in new_pkg/src/lib.rs (and other new_pkg/src/*.rs files)
5. To export a function fn inc(x: i32) -> i32 in the namespace xyz, add its declaration to new_pkg/src/lib.rs as follows:

#[cxx::bridge(namespace = "xyz")]
mod ffi {
    extern "Rust" {
        fn inc(x: i32) -> i32;
    }
}

6. Add new_pkg/src/lib.rs to the configure.py dependencies where you'll need the Rust exports
7. Include the rust/new_pkg.hh header and use xyz::foo() in the selected c++ file.

cxx::bridge placement

You can put the cxx::bridge segment into some file other than lib.rs as well, for example abc.rs. If you do that, remember to add mod abc to lib.rs to make sure that the bridge is compiled with the entire package. Additionally, the definitions of exported functions must be visible in abc.rs. You can achieve this writing them in the same file or using mod and use statements. Then, use this file instead of lib.rs in the configure.py dependencies.

Submitting changes

Additionally to the source code, Scylla tracks the Cargo.lock file that contains precise information about dependency versions used in the last successful build. Dependency modification may include:

• adding a new local package (it is used in Scylla as a dependency)
• updating a dependency version in an existing package
• adding a new dependency to a package

After each such modification, a new Cargo.lock file should be submitted. Cargo.lock can be generated by the cargo update command.

Rust interoperability implementation

Using Rust alongside C++ in scylla is made possible by the Rust crate CXX. The cxx::bridge macro, together with mod ffi and extern "Rust" mark items to be exported to C++. During compilation of Rust files, a static library using C++ ABI is generated. The library exports Rust methods under special names. These names are used in the implementations of C++ methods with the original names. The C++ methods are listed in *.hh files, and their implementations in *.cc files, both generated from the Rust source code using cxxbridge command. The header exposes all items with original names and can be included like any other C++ header.

Compilation is managed by cargo. Like in any Rust project, modules added to Scylla can be fully customized using corresponding Cargo.toml files. All modules are compiled to single static library, as this is the only officially supported way of linking Rust against C++. In the future, more linking methods may become supported, possibly using rlib ("Rust library") files.