A little Rust with your C

Using Rust code inside a C or C++ project mostly consists of two parts.

• Creating a C-friendly API in Rust
• Embedding your Rust project into an external build system

Apart from cargo and meson, most build systems don't have native Rust support.So you're most likely best off just using cargo for compiling your crate andany dependencies.

Setting up a project

Create a new cargo project as usual.

There are flags to tell cargo to emit a systems library, instead ofits regular rust target.This also allows you to set a different output name for your library,if you want it to differ from the rest of your crate.

[lib]
name = "your_crate"
crate-type = ["cdylib"]      # Creates dynamic lib
# crate-type = ["staticlib"] # Creates static lib

Building a C API

Because C++ has no stable ABI for the Rust compiler to target, we use C forany interoperability between different languages. This is no exception when using Rustinside of C and C++ code.

#[no_mangle]

The Rust compiler mangles symbol names differently than native code linkers expect.As such, any function that Rust exports to be used outside of Rust needs to be toldnot to be mangled by the compiler.

extern "C"

By default, any function you write in Rust will use theRust ABI (which is also not stabilized).Instead, when building outwards facing FFI APIs we need totell the compiler to use the system ABI.

Depending on your platform, you might want to target a specific ABI version, which aredocumented here.

Putting these parts together, you get a function that looks roughly like this.

#[no_mangle]
pub extern "C" fn rust_function() {
}

Just as when using C code in your Rust project you now need to transform datafrom and to a form that the rest of the application will understand.

Linking and greater project context.

So then, that's one half of the problem solved.How do you use this now?

This very much depends on your project and/or build system

cargo will create a my_lib.so/my_lib.dll or my_lib.a file,depending on your platform and settings. This library can simply be linkedby your build system.

However, calling a Rust function from C requires a header file to declarethe function signatures.

Every function in your Rust-ffi API needs to have a corresponding header function.

#[no_mangle]
pub extern "C" fn rust_function() {}

would then become

void rust_function();

etc.

There is a tool to automate this process,called cbindgen which analyses your Rust codeand then generates headers for your C and C++ projects from it.

At this point, using the Rust functions from Cis as simple as including the header and calling them!

#include "my-rust-project.h"
rust_function();