cxx

CXX provides safe FFI between Rust and C++ by allowing developers to write idiomatic code on both sides of the boundary.

Key features include:

• Idiomatic code: Rust code looks like normal Rust, and C++ code looks like normal C++, avoiding the need for manual, error-prone C-style FFI glue.
• Type Safety: Uses an expressive system of opaque types, shared types, and standard library type bindings.
• Ownership and Borrowing: Enables API design that captures the proper ownership and borrowing contracts of the interface across the language boundary.

The CXX C++ code generator provides two primary public frontends for integrating C++ code generation into your workflow:

1. Command-line application: A binary located in the cmd directory for direct execution.
2. Build script library: A library located in the build directory intended to be used within a build.rs file for automated integration during the Rust build process.

Note: There is also a lib frontend for embedding CXX into higher-level code generators, but its use is not yet recommended for general purposes.

CXX is designed to be a restrictive and opinionated FFI library to provide strong safety guarantees. Unlike manual extern "C" blocks in Rust, which are prone to signature mismatches, CXX uses paired code generators to ensure both the Rust and C++ sides of the FFI boundary are synchronized.

Key safety features include:

• Signature Visibility: The generators ensure Rust knows exactly what is on the C++ side.
• Static Analysis: Prevents passing types by value from C++ to Rust if they contain internal pointers that would be invalidated by Rust's move semantics.
• ABI Correctness: Automatically handles zero-cost workarounds for cases where Rust and C++ structs have identical layouts but different ABIs (addressing known issues in tools like bindgen).
• Template Support: Uses Rust traits to connect Rust types to C++ template instantiations (e.g., UniquePtr<T>).

To start a new project using CXX, create a standard Cargo project and add cxx to your dependencies in Cargo.toml.

# Cargo.toml
[package]
name = "cxx-demo"
version = "0.1.0"
edition = "2024"

[dependencies]
cxx = "1.0"

mkdir cxx-demo
cd cxx-demo
cargo init

Use the extern "C++" block within a #[cxx::bridge] module to bind C++ functionality to Rust. This allows you to:

• Bind opaque C++ types
• Bind C++ functions
• Bind C++ member functions
• Share opaque type definitions across multiple bridge modules or different crates
• Use bindgen-generated data structures across a CXX bridge
• Request specific glue code emission in a specific bridge module in a way that is compatible with Rust orphan rules

Shared types allow both Rust and C++ to access the internals of a type. Unlike opaque types, shared types can be passed and returned by value.

Constraints:

• For enums, only C-like (unit) variants are supported.
• CXX automatically handles topological sorting and forward declarations, so the order of definition in the #[cxx::bridge] module does not matter.
• If a shared struct has generic lifetime parameters, they are not represented on the C++ side; C++ code must manually manage borrowed data safety.

#[cxx::bridge]
mod ffi {
    struct PlayingCard {
        suit: Suit,
        value: u8,  // A=1, J=11, Q=12, K=13
    }

    enum Suit {
        Clubs,
        Diamonds,
        Hearts,
        Spades,
    }

    unsafe extern "C++" {
        fn deck() -> Vec<PlayingCard>;
        fn sort(cards: &mut Vec<PlayingCard>);
    }
}

You can inspect the code generated by CXX for both languages using the following commands:

• Rust code: Requires cargo-expand. Run cargo expand --manifest-path <path-to-toml>.
• C++ code: Use the cxxbridge-cmd tool via cargo run from the bridge command directory.

# run Rust code generator and print to stdout
# (requires https://github.com/dtolnay/cargo-expand)
$ cargo expand --manifest-path demo/Cargo.toml

# run C++ code generator and print to stdout
$ cargo run --manifest-path bridge/cmd/Cargo.toml -- demo/src/main.rs

Use a build.rs script to invoke the cxx_build code generator. You must specify the Rust file containing the #[cxx::bridge] definition and the paths to the C++ source files to be compiled.

// build.rs
fn main() {
    cxx_build::bridge("src/main.rs")
        .file("src/blobstore.cc")
        .std("c++14")
        .compile("cxx-demo");

    println!("cargo:rerun-if-changed=src/blobstore.cc");
    println!("cargo:rerun-if-changed=include/blobstore.h");
}

Manage fallibility between Rust and C++ using the bridge module. Capabilities include:

• Representing fallibility on the language boundary
• Accessing Rust error messages from C++
• Customizing the set of caught C++ exceptions and their conversion into Rust error messages