Customizing bindings using annotations

The Rust bindings for a C++ declaration can be customized using an attribute macro from "support/annotations.h".

For instance:

  • A function can be marked unsafe in Rust, even if Crubit would otherwise assume it was safe, using CRUBIT_UNSAFE.
  • Missing bindings for an item can be treated as an error, instead of ignored, using CRUBIT_MUST_BIND.
  • An item can be given a different name in Rust using CRUBIT_RUST_NAME("rust_name_here").
  • A function or method can be given pub(crate) visibility in Rust, limiting its visibility to the generated crate (including custom srcs on rust_api_from_cpp), using CRUBIT_PUB_CRATE.
  • A non-trivial type with a custom move constructor or destructor can be marked Rust-movable (Unpin) without changing its C++ calling-convention ABI using CRUBIT_UNSAFE_BITWISE_RELOCATABLE (or _IF_ELIGIBLE for templates, _FIELD for fields, and CRUBIT_NEVER_BITWISE_RELOCATABLE to force pinning).

More information:

  • Dependency: //support:annotations
  • Include: #include "support/annotations.h"
  • Full API documentation: support/annotations.h

Example

Given the following C++ header:

cs/file:examples/cpp/unsafe_attributes/example.h content:SafeSignatureButAnnotatedUnsafe

Crubit will generate the following bindings:

cs/file:examples/cpp/unsafe_attributes/example_generated.rs symbol:SafeSignatureButAnnotatedUnsafe