features/README.md

# Crubit Features

<internal link>

NOTE: b/262878759: Features are currently only used for autogenerated Rust
bindings of C++ targets, not C++ bindings of Rust targets. Even without
specifying any features, Crubit will generate full C++ bindings for Rust
targets. This will change soon.

<!-- TODO(b/262878759): see above. -->

C++/Rust interop is configured per target using "features": aspect hints which
are applied onto a build target in order to configure its automatically
generated bindings.

Features control which capabilities Crubit has. For example, support for move
constructors is gated behind the `:experimental` feature. If the class is in a
target configured to use `:experimental`, then the constructor will receive
bindings, otherwise it will not.

Features are used for gradual rollouts of new capabilities, and to allow for
separate build modes for un-annotated code, code which opts into C++/Rust
interop, and internal test code.

To use a feature, add it to your target:

```python
# Enables the `:supported` feature on a C++ library `:example`.
cc_library(
    name = "example",
    hdrs = ["example.h"],
    aspect_hints = ["//features:supported"],
)
```

This causes the generated bindings for that target to use all the Crubit
capabilities in `:supported`.

## Features

### <default> {#default}

The default feature is enabled for all targets everywhere. It contains interop
capabilities which have minimal impositions on library owners.

The default feature currently only enables a "dark launch" parsing and
processing pass. No bindings are generated.

### `"//features:supported"` {#supported}

The `supported` feature enables generally-available C++/Rust interop
capabilities, for libraries that specifically support FFI callers.

See <internal link> for documentation on what this includes.

### `"//features:extern_c"` {#extern_c}

`extern_c` is the feature for the in-development version of Crubit. For calling
C++ from Rust, use `:supported` instead.

### `"//features:experimental"` {#experimental}

The `experimental` feature enables internal-only experimental capabilities. This
is used for testing of upcoming features, and is also used by pilot partners who
are testing those features. This also includes everything in `:supported`.

`experimental` is visibility-restricted to only internal use and pilot partners.