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.

## Using Features

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`.

## Testing Features

Crubit developers may want to temporarily enable features without respect to
visibility restrictions or level of support. The build flag:

`--//rs_bindings_from_cc/bazel_support:globally_enabled_features`

accepts a comma-separated list of unstable internal feature names (like
`supported`, `experimental`, or the special alias `all`) and overrides the
baseline feature set for all targets for the duration of the build. The flag's
default value is the empty list.

## 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: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.