A C++ class or struct is mapped to a Rust struct with the same fields. If any subobject of the class cannot be represented in Rust, the class itself will still have bindings, but the relevant subobject will be private.
Given the following C++ header:
cs/file:examples/cpp/trivial_struct/example.h class:Position
Crubit will generate a struct with the same layout:
cs/file:examples/cpp/trivial_struct/example_generated.rs class:Position
Which can be used like this:
cs/file:examples/cpp/trivial_struct/main.rs function:main
For an example of a Rust-movable class with a destructor, see examples/cpp/trivial_abi_struct/.
The fields on the Rust struct type are the corresponding Rust types:
T[N]) of a primitive type or enum (including multidimensional arrays such as T[M][N]), then the Rust field has type [T; N].Subobjects that do not receive bindings are made private, and replaced with an opaque blob of [MaybeUninit<u8>; N], as well as a comment in the generated source code explaining why the subobject could not receive bindings. For example, base class subobjects are not exposed as fields, so the space of the object occupied by a base class will instead be this opaque blob of bytes, with no comment. (See Base classes for what you can do with base classes instead.)
Specifically, the following subobjects are hidden and replaced with opaque blobs:
public fields (private or protected fields)no_unique_address#[repr(align(N))]A Rust struct with opaque blobs is ABI-incompatible with the C++ struct or class that it corresponds to. As a consequence, if the struct is used for FFI outside of Crubit, it should not be passed by value. Within Crubit, it can't be passed by value in function pointers, but can otherwise be used as normal.
Public static data members get bindings: compile-time integer, bool, integer array, and string_view constants become associated consts of the Rust struct, and other static data members become Rust statics. See Static data members for details.
The easiest C++ classes to work with are “Rust-movable”, meaning they support being relocated in memory using memcpy without running the move constructor. When passed and returned by value, Rust-movable classes will use the direct type. For example, T Identity(T) becomes pub fn Identity(_: T) -> T.
If it is non-Rust-movable, then Crubit will instead use in-place initialization types, Ctor, and requires a bit of syntactic overhead when moving objects around. The same function might instead become pub fn Foo(_: Ctor![T]) -> Ctor![T].
(For an introduction to Ctor![T], see crubit.rs/types/non_rust_movable/intro_short.)
Types are considered Rust-movable (bitwise relocatable) by default. If the type defines a user-provided move constructor or destructor, then it requires a special annotation to be considered Rust-movable: CRUBIT_UNSAFE_BITWISE_RELOCATABLE (defined in support/annotations.h, along with CRUBIT_UNSAFE_BITWISE_RELOCATABLE_IF_ELIGIBLE for templates, CRUBIT_UNSAFE_BITWISE_RELOCATABLE_FIELD, CRUBIT_BITWISE_RELOCATABLE_STD_STRING_ONLY_ON_LIBCXX, and CRUBIT_NEVER_BITWISE_RELOCATABLE).
If a type has a non-Rust-movable field or base class, it is not Rust-movable. A CRUBIT_UNSAFE_BITWISE_RELOCATABLE annotation on a type with non-bitwise-relocatable fields or bases fails bindings generation with a hard error.
Note on trivial_abi: While [[clang::trivial_abi]] / ABSL_ATTRIBUTE_TRIVIAL_ABI previously made types Rust-movable, it may not make a type Rust-movable anymore. Crubit checks the members of a trivial_abi type, and if any member is not bitwise-relocatable, Crubit leaves the type pinned and records the reason in the generated doc comment. New code should use CRUBIT_UNSAFE_BITWISE_RELOCATABLE.
It can be worth putting some effort into designing the type to be Rust-movable. The C++ Bindings Cookbook describes, in more detail, how to go about this.
Some examples of Rust-movable types:
string_viewstruct tm, or any other type in the C standard librarystd::unique_ptr (with the default deleter), std::shared_ptr, std::weak_ptr, and std::vector (with the default allocator)std::optional<T>, std::variant<Ts...>, and std::expected<T, E> when their element types are Rust-movable= deleted) special member functions, even if its copy and move constructors are implicitly deleted (such as structs containing rs::Box or other non-C++-movable types annotated with CRUBIT_UNSAFE_BITWISE_RELOCATABLE).absl::StatusSome examples of types that are not Rust-movable:
std::string (unless opted in on libc++-only builds via CRUBIT_BITWISE_RELOCATABLE_STD_STRING_ONLY_ON_LIBCXX), std::function, std::any, and node-based containers such as std::map and std::list.absl::flat_hash_map, absl::AnyInvocable, and other nontrivial types used throughout the C++ ecosystem, even outside the standard library.absl::Mutex, absl::Notification, and other non-movable types.Rust has no inheritance, so a derived class and its base classes become unrelated Rust structs. The base class subobject is an opaque blob, so base class fields aren't accessible through the derived struct. With oo_casting, Rust code can upcast to the base class and read the fields there.
By default, methods that a class inherits from its base classes are not part of the derived class‘s bindings, and no comment is emitted about them. They still exist on the base class’s bindings.
struct Base { bool IsValid() const; }; struct Derived : Base {};
Here, Base::IsValid() has bindings, but Derived has no IsValid() method in Rust.
To get inherited methods, add //features:oo_casting to the aspect_hints of the cc_library that defines the derived class. This is an experimental feature. With it:
The derived struct gets the public methods, including static methods, of its public base classes, so derived.IsValid() works in Rust. This only covers base classes defined in the same cc_library as the derived class, and leaves out methods whose name comes from more than one base class.
The derived struct implements oops::Inherits<Base> for each public base class, including base classes from other cc_library targets. Rust code can then use the oops::Upcast trait to convert a &Derived to the base class type. If the base class is not Rust-movable, it can also convert a Pin<&mut Derived>. To convert a *const Derived or *mut Derived, use oops::RawUpcast. For example, to call a method of a base class in another cc_library, upcast first:
use oops::Upcast as _; // The type annotation is required. let base: &Base = unsafe { derived.upcast() }; // For non-const methods on a non-Rust-movable base class: let base: core::pin::Pin<&mut Base> = unsafe { derived_pin.upcast() }; // For raw pointers: use oops::RawUpcast as _; let base_ptr: *const Base = unsafe { derived_ptr.raw_upcast() };
There is no Pin<&mut Derived> conversion to a Rust-movable base class, because safe code could turn the result into a &mut Base and overwrite data that belongs to the derived class.
For a virtual base class, use oops::VirtualUpcast on a raw pointer instead. Rust code that uses these traits depends on //support:oops.
The tests in rs_bindings_from_cc/test/struct/inheritance/ show both.
Without oo_casting, add a method to the derived class in C++ that forwards to the base class method, or a function that returns the object as a pointer to its base class.
using Base::Method; declarations in the derived class don‘t get bindings, and produce a “Function aliases are not yet supported” error comment. With oo_casting, the method is usually inherited anyway. It’s missing only if the using declaration makes a method of a non-public base class accessible, or brings back a base class method that a derived class method of the same name hides.
Calling a C++ virtual method from Rust works like calling any other method, and dispatches virtually. This includes pure virtual methods. Because a class with virtual methods is not Rust-movable, non-const methods take self: Pin<&mut Self>.
An abstract class (one with pure virtual methods that aren‘t overridden) gets bindings for its methods but no constructor, so Rust code works with it through references and pointers to objects created elsewhere. A subclass that overrides the methods gets bindings for its overrides and can be constructed. The methods it doesn’t override are inherited methods.
Overriding a C++ virtual method in Rust, or otherwise implementing a C++ interface in Rust, is not supported. The workaround is a C++ subclass that forwards to a Rust type; see examples/cpp/virtual/.
With the experimental //features:record_impl_debug feature, Crubit automatically generates an impl Debug for C++ structs and classes, unless:
Debug.CRUBIT_OVERRIDE_DEBUG(false).The generated impl Debug formats all supported fields that implement Debug. If all fields are supported and debug-formattable, and the type has no bases, it calls .finish() (exhaustive). Otherwise, it calls .finish_non_exhaustive() to indicate that some C++ details may be omitted e.g., unsupported fields, other bases.
To manually control whether to generate the impl Debug, use the CRUBIT_OVERRIDE_DEBUG macro:
cs/file:support/annotations.h symbol:CRUBIT_OVERRIDE_DEBUG
CRUBIT_OVERRIDE_DEBUG(false): Use if the C++ type already has a hand-written Rust Debug implementation to avoid a trait implementation conflict.CRUBIT_OVERRIDE_DEBUG(true): Use to force generation for an abstract type.IMPORTANT: Deriving Debug using CRUBIT_TRAIT_DERIVE("Debug") will be deprecated and cause a compilation error. Use the default behavior or CRUBIT_OVERRIDE_DEBUG instead.
A packed C++ struct becomes a packed Rust struct with the same layout:
__attribute__((packed)) (or ABSL_ATTRIBUTE_PACKED) on the struct becomes #[repr(C, packed)].#pragma pack(N) becomes #[repr(C, packed(N))]. If the pragma doesn‘t lower the alignment of any field or base class, it doesn’t change the layout, and the struct is treated like any other struct.For example:
struct __attribute__((packed)) PackedStruct { uint8_t a; uint32_t b; // At offset 1. uint16_t c; // At offset 5. };
becomes a 7-byte Rust struct with alignment 1:
#[repr(C, packed)] pub struct PackedStruct { pub a: u8, pub b: u32, pub c: u16, }
Some packed structs don't get bindings:
__attribute__((packed)) on individual fields.alignas or __attribute__((aligned(N)))) greater than the packing alignment.A field of a packed struct whose Rust type has #[repr(align(N))], directly or in one of its own fields, becomes a private opaque blob, because Rust doesn‘t allow such types in packed structs. A struct type gets #[repr(align(N))] if, for example, it has an explicit alignment, or it has an alignment greater than 1 and has bitfields or fields whose type doesn’t have bindings.
Note: Clang doesn‘t pack fields whose type isn’t POD for the purpose of layout (for example, a type with a user-defined copy constructor) and warns about this with -Wpacked-non-pod. If such a field has an alignment greater than 1, the Rust bindings won't compile, because the Rust struct packs every field.
Fields of a packed struct may be unaligned, so Rust doesn‘t allow references to them (E0793). Reading a field by value (let b = s.b;) works, but anything that implicitly takes a reference, such as println!("{}", s.b) or s.b.to_string(), doesn’t compile. Copy the field out first, for example with braces:
println!("{}", { s.b }); let text = { s.b }.to_string();
Assigning to a field (s.b = 5;) works as usual. For fields that aren't Copy, use raw pointers (&raw const s.field or &raw mut s.field) with ptr::read_unaligned and ptr::write_unaligned.
Debug for packed structs {#packed_debug}Crubit ignores CRUBIT_TRAIT_DERIVE(Debug) on packed structs, because #[derive(Debug)] takes references to the fields.
Instead, with the experimental //features:record_impl_debug feature, packed structs implement Debug like other structs, with these differences:
Copy (or is mutable, and thus wrapped in a Cell), no fields are printed, and the output is PackedStruct { .. }, like for a union.For example, with the struct above, format!("{s:?}") is PackedStruct { a: 10, b: 200, c: 3000 }. The tests in rs_bindings_from_cc/test/struct/packed/ show more examples.
Crubit does not support most attributes on structs and their fields. If a struct is marked using any attribute other than alignment, packing, CRUBIT_* annotations from "support/annotations.h" (such as CRUBIT_UNSAFE_BITWISE_RELOCATABLE, which should be preferred over ABSL_ATTRIBUTE_TRIVIAL_ABI in new code), or ABSL_ATTRIBUTE_TRIVIAL_ABI, it will not receive bindings. If a field is marked using any other attribute (aside from supported annotations such as CRUBIT_* field annotations), it will be replaced with a private opaque blob.