When not using libc++’s unstable ABI, the most straightforward way to make a field Rust-movable is to instead use a raw pointer, and delete it in the destructor (as if it were held by a unique_ptr).

struct Person {
  std::string name;
  int age;
}

struct ABSL_ATTRIBUTE_TRIVIAL_ABI Person {
  // Owned, boxed to make Person rust-movable: crubit.rs/cpp/cookbook#boxing
  std::string* name;
  int age;

  ~Person() {
    delete name;
  }
}

(Note the use of ABSL_ATTRIBUTE_TRIVIAL_ABI: because we added a destructor, we also need to add ABSL_ATTRIBUTE_TRIVIAL_ABI to indicate that the destructor does not care about the address of Person.)

Before CRUBIT_THREAD_SAFE was available, or if you cannot annotate the class directly, making a mutating C++ method safe to call concurrently in Rust required a manual workaround:

1. The class must be documented as thread-safe.
2. The field being mutated must be marked as mutable, even if it is only mutated in non-const methods, so that internal mutation in Rust does not cause UB.
3. The method must be manually wrapped in a C++ const method (or wrapped in Rust with unsafe casts).

Due to b/481398972, the mutated field cannot be public. Due to b/481405536, the class itself must not be trivially copyable.

Example of manual wrapping:

class FakeClock {
 public:
  // The destructor is only here to make the type non-trivially copyable.
  // TODO(b/481405536): Remove the destructor once this bug is fixed.
  ~FakeClock() {}
  CRUBIT_RUST_NAME("advance_mut")
  void Advance(int n) {
    DoNotUseForRustOnlyAdvance(n);
  }

  CRUBIT_RUST_NAME("advance")
  void InternalDoNotUseForRustOnlyAdvance(int n) const {
    mytime_ += n;
  }
 private:
  // Mutable for Rust.
  mutable int mytime_;
};

You can also use the CRUBIT_THREAD_SAFE annotation, but this is more dangerous, as there is no enforcement that every method only modifies mutable fields, and requires more extensive review:

class CRUBIT_THREAD_SAFE FakeClock {
  ...
};

Using const methods, while less idiomatic in C++, structurally forces soundness, so that there is no UB.

## Working around blocking bugs in Crubit {#blockers}

Crubit is still in development, and has bugs which can completely stop your work
if Crubit was in the critical path. These can take the form of parsing errors or
crashes when Crubit runs, or else generated bindings which do not compile.

The following workarounds can help get you moving again:

### Disable Crubit on a declaration {#disable-declaration}

If a declaration causes hard failures within Crubit, that declaration alone can
be disabled using the `CRUBIT_DO_NOT_BIND` attribute macro:

```c++
#include "support/annotations.h"

CRUBIT_DO_NOT_BIND  // b/123: Crubit crashes on std::crash_rust_plz_t
void foo(std::crash_rust_plz_t*);
```

> NOTE: By disabling Crubit on this declaration, items which depend on it may
> also, in turn, not receive bindings. For example, if it declares a type, then
> functions which accept or return that type will also not receive bindings.
>
> For that reason, except for functions, `CRUBIT_DO_NOT_BIND` requires modifying
> an allowlist at
> rs_bindings_from_cc/bazel_support/generate_bindings.bzl.
> Changes to that file are most easily mailed using <internal link>_manage: add
> `AUTO_MANAGE=testing:TGP` to the CL description.

### Disable Crubit on a header {#disable-header}

If an entire header is giving problems (e.g. is unparseable), then it can be
removed from consideration by Crubit. Once disabled, Crubit will avoid reading
the header directly, although it is still included via `#include` preprocessor
directives.

Add the target name and header name to `public_headers_to_remove` in
rs_bindings_from_cc/bazel_support/rust_bindings_from_cc_aspect.bzl.
See the example in
rs_bindings_from_cc/test/disable/disable_header/.

To mail the CL performing this change, use <internal link>_manage: add
`AUTO_MANAGE=testing:TGP` to the CL description.

> NOTE: By disabling Crubit on this header, items which are defined in that
> header will not receive bindings. For example, this means that functions which
> use types defined in that header will also not get bindings, even if the
> function was defined in a header that was not disabled.
>
> When possible, it's preferable to use a smaller fix. For example, if the same
> header is owned by two targets, it's preferable to move the header into a
> third target, depended on by both. That way, functions which use types defined
> in that header will still get bindings, in both targets.

## Making backwards-compatible changes to C++ code with Rust callers {#compatibility}

Because Rust does not have all the features C++ does, some changes that do not
*usually* break a C++ caller can break a Rust caller. For example, most C++
callers will not be broken by adding a new overload to an overload set, but that
does break Rust callers, because Rust doesn't have overloading.

Most of the time, you can think of Rust users (and Crubit) as the most
pathological possible C++ caller, relying on all the details of your API.

The following sections attempt to be an exhaustive list of the things you might
expect to be able to do if you only have C++ callers, but cannot do with Rust
callers.

### Making a type non-Rust-movable {#compatibility-non_movable}

If a type is made non-Rust-movable, when it was previously Rust-movable, this
will break all but the most trivial of Rust callers.

Specifically, the following operations are compatibility-breaking if the type
was Rust-movable:

*   Adding a virtual method.
*   Adding a user-defined copy constructor, move constructor, or destructor,
    without specifying `ABSL_ATTRIBUTE_TRIVIAL_ABI`.
*   Adding a non-Rust-movable field or base class (such as `std::string`).

```c++ {.no-copy}
struct Before {
  int x;
};
struct After {
  ~After() {}

  int x;
  std::string y;
};

Before ReturnBefore();
After ReturnAfter();
```

```rust {.no-copy}
#[derive(Copy, Clone)]
struct Before {...}
struct After {...}

pub fn ReturnBefore() -> Before {...}
pub fn ReturnAfter() -> Ctor![After] {...}
```

**Fix:** Preserve Rust-movability, as described above in
[Making types Rust-movable](#rust_movable)

```c++ {.good, .no-copy}
class ABSL_ATTRIBUTE_TRIVIAL_ABI CompatibleAfter {
  ~After() {}

  int x;
  std::unique_ptr<std::string> y;
};
```

### Adding or removing virtual destructors {#compatibility-polymorphic}

If a type's destructor is made virtual, or was previously virtual and now
becomes nonvirtual, this changes how Rust callers invoke destruction. For
example, `unique_ptr<T>` becomes `virtual_unique_ptr<T>` if `T` has a virtual
destructor.

```c++ {.no-copy}
class Before {};
class After {~After(){}};

std::unique_ptr<Before> ReturnBefore();
std::unique_ptr<After> ReturnAfter();
```

```rust {.no-copy}
pub fn ReturnBefore() -> cc_std::std::unique_ptr<Before> {...}
pub fn ReturnAfter() -> cc_std::std::virtual_unique_ptr<After> {...}

let _: cc_std::std::unique_ptr<_> = ReturnAfter();  // error[E0308]: mismatched types
```

**Fix:** Migrate callers that use heap allocated types such as `unique_ptr`.

```rust {.good .no-copy}
let _: cc_std::std::virtual_unique_ptr<_> = ReturnAfter();
```

### Adding an overload {#compatibility-overload}

Except for constructors and operators, adding an overload to a C++ function will
cause it to no longer receive bindings, unless the overloads are given distinct
names in Rust (via `CRUBIT_RUST_NAME`).

```c++ {.no-copy}
void Before();

void After();
void After(int);
```

```rust {.no-copy}
pub fn Before() {...}
// No bindings for After.
```

**Fix:** Use `CRUBIT_RUST_NAME("NewName")` to specify a per-overload name.

```c++ {.good .no-copy}
void CompatibleAfter();

CRUBIT_RUST_NAME("CompatibleAfterInt")
void CompatibleAfter(int);
```

```rust {.good .no-copy}
pub fn CompatibleAfter() {...}
pub fn CompatibleAfterInt(_: c_int) {...}
```

### Changing types with implicit conversions {#compatibility-conversions}

In C++, it is often compatible to change from, for example, accepting an
`int32_t` to a `int64_t`, or similar. This is not a compatible change in Rust,
because implicit conversions do not exist.

```c++ {.no-copy}
void Before(int32_t);
void After(int64_t);
```

```rust {.no-copy}
pub fn Before(_: i32) {...}
pub fn After(_: i64) {...}

let x: i32 = ...;
After(x);  // error[E0308]: mismatched types
```

**Fix:** Migrate callers.

```rust {.good .no-copy}
After(x.into())
```

### Unsupported features {#compatibility-unsupported}

Use of other unsupported features of C++, such as `decltype` or various
unsupported clang attributes, will also cause breakages for Rust callers.

This is an open-ended failure category, and includes, at minimum:

*   Changing from a concrete function to a template function
*   Changing from an ordinary class to a type alias to a template specialization
*   Unrecognized attributes
*   Types that do not have Crubit support yet

For instance:

```c++ {.no-copy}
int Before(int x) {...}

[[clang::very_interesting_advanced_attribute]]
auto After(int x) -> decltype(x + std::declval<int>()) {...}
```

```rust {.no-copy}
pub fn Before(_: c_int) -> c_int {...}
// No bindings for After
```

**Fix:** Avoid the use of these features, or wrap with Rust-only functions that
avoid the use of these features.

```c++ {.good .no-copy}
int CompatibleAfter(int x) {return After(x);}
```

```rust {.good .no-copy}
pub fn After(_: c_int) -> c_int {...}
```