cxx

cxx is a Rust library that provides a safe mechanism for calling C++ code from Rust and vice versa, avoiding the unsafe raw bindings that tools like bindgen or cbindgen generate. Both sides of the FFI boundary are declared together in an #[cxx::bridge] Rust module, from which cxx performs static analysis of the types and function signatures to enforce both languages’ invariants at compile time.

The core safety claim is that C++ code is inherently unsafe to audit either way, but with cxx the Rust side of the boundary can be 100% safe — so auditing just the C++ side is sufficient to catch cross-language memory-safety problems. It’s built and maintained by dtolnay (also known for serde, anyhow, thiserror) and is used in production by projects including Firefox, Android’s Rust/C++ boundary work, and various embedded and systems projects needing incremental Rust adoption inside existing C++ codebases.

What You Get

• A #[cxx::bridge] proc-macro for declaring shared types and function signatures once, in one place
• Compile-time verification that both sides of the FFI boundary agree on types and signatures
• Safe, ergonomic Rust-native types for common C++ constructs (UniquePtr, CxxString, CxxVector, shared structs/enums)
• The cxx-build companion crate that generates and compiles the C++ glue code as part of your Cargo build
• Support for calling from either direction — Rust calling C++ and C++ calling Rust — in the same bridge
• An extensive book (cxx.rs) with a tutorial and full reference of supported bridged types

Common Use Cases

• Incrementally rewriting parts of a large C++ codebase in Rust without an unsafe, error-prone FFI layer
• Embedding an existing C++ library (e.g. a codec, parser, or hardware SDK) inside a Rust application
• Exposing Rust functionality to a C++ host application (browser engines, game engines, embedded firmware)
• Building cross-language libraries where both a C++ and Rust API need to share the same underlying implementation

Under The Hood

Architecture - The crate is split into a proc-macro (macro/) that parses #[cxx::bridge] modules using a shared syntax/ crate for the mini-IR describing the boundary, a bridge/ subtree containing cxx-build (invokes a C++ compiler via the cc crate to compile generated glue) and cxx-gen (the codegen engine producing matching Rust and C++ source from the parsed IR), and a runtime support library (src/) providing the safe wrapper types (UniquePtr, CxxString, CxxVector) that the generated code binds against; include/ ships the C++-side header counterparts.

Tech Stack - Rust 2024 edition (MSRV 1.85) for the macro/runtime, C++11-or-newer for the generated glue and test fixtures, with cc driving the C++ compiler invocation, foldhash for internal hashing, and link-cplusplus to correctly link the C++ standard library; build systems beyond Cargo (Buck2, Bazel) are supported via committed BUCK/BUILD.bazel/MODULE.bazel files, reflecting its use inside large monorepos.

Code Quality - The tests/ directory contains 94+ Rust test files plus a full C++ FFI test suite (tests/ffi) exercising both directions of the bridge, CI runs across multiple Rust/C++ toolchain combinations, and the crate has years of stable, incremental releases (1.0.x since inception) with a strict internal versioning scheme tying cxx, cxxbridge-macro, and cxx-gen together — indicating disciplined release management for a project used in safety-sensitive production code.

API Design - The single #[cxx::bridge] macro entry point with declarative type/signature listing is a deliberately narrow, well-documented surface (fully specified in the cxx.rs book), and safe wrapper types like UniquePtr<T>/CxxString map cleanly onto their C++ counterparts; the tradeoff is a real learning curve around which types are bridgeable and how ownership crosses the boundary, which the extensive external documentation exists specifically to address.