Files

Wojciech Mitros 4d7858e66d rust: adjust build according to cxxbridge's recommendations

Currently, the rust build system in Scylla creates a separate
static library for each incuded rust package. This could cause
duplicate symbol issues when linking against multiple libraries
compiled from rust.

This issue is fixed in this patch by creating a single static library
to link against, which combines all rust packages implemented in
Scylla.

The Cargo.lock for the combined build is now tracked, so that all
users of the same scylla version also use the same versions of
imported rust modules.

Additionally, the rust package implementation and usage
docs are modified to be compatible with the build changes.

This patch also adds a new header file 'rust/cxx.hh' that contains
definitions of additional rust types available in c++.

2023-01-06 14:05:53 +01:00

3.1 KiB

Raw Blame History

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:

Create a new package in the rust directory using cargo new new_pkg --lib
Add new_pkg = { path = "new_pkg", version = "0.1.0" } to the dependencies list in rust/Cargo.toml
Add extern crate new_pkg; to rust/src/lib.rs
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)
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;
    }
}

Add new_pkg/src/lib.rs to the configure.py dependencies where you'll need the Rust exports
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. It will also update after each build that modifies the dependencies.

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.

3.1 KiB Raw Blame History