tree: 69008841a09422bbd79098695c3fdb7305d571d7 [path history] [tgz]
  1. BUILD
  2. README.md
features/README.md

Crubit Features

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.

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:

# 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, non_extern_c_functions, or experimental) 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

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"

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

See for documentation on what this includes.

"//features: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.