rules_rust_bindgen
These rules are for using Bindgen to generate Rust bindings to C (and some C++) libraries.
Rules
Setup
To use the Rust bindgen rules, add the following to your MODULE.bazel file:
bazel_dep(name = "rules_rust_bindgen", version = "{SEE_RELEASE_NOTES}")
rules_rust_bindgen does not automatically register a bindgen toolchain.
You need to register either your own or the default toolchain by adding the following to your MODULE.bazel file:
register_toolchains("@rules_rust_bindgen//:default_bindgen_toolchain")
The default toolchain builds libclang from source via the llvm-project bazel_dep. examples/bindgen_toolchain shows how to use a prebuilt libclang.
Bindgen aims to be as hermetic as possible so will end up building libclang from llvm-project from
source. If this is found to be undesirable, users should define their own repositories using something akin to
crate_universe and define their own toolchains following the instructions for
rust_bindgen_toolchain.
rust_bindgen
load("@rules_rust_bindgen//:defs.bzl", "rust_bindgen")
rust_bindgen(name, bindgen_flags, cc_lib, clang_flags, header, merge_cc_lib_objects_into_rlib,
wrap_static_fns)
Generates a rust source file from a cc_library and a header.
ATTRIBUTES
| Name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| name | A unique name for this target. | Name | required | |
| bindgen_flags | Flags to pass directly to the bindgen executable. See https://rust-lang.github.io/rust-bindgen/ for details. | List of strings | optional | [] |
| cc_lib | The cc_library that contains the .h file. This is used to find the transitive includes. | Label | required | |
| clang_flags | Flags to pass directly to the clang executable. | List of strings | optional | [] |
| header | The .h file to generate bindings for. | Label | required | |
| merge_cc_lib_objects_into_rlib | When True, objects from cc_lib will be copied into the rlib archive produced by the rust_library that depends on this rust_bindgen rule (using BuildInfo provider) | Boolean | optional | True |
| wrap_static_fns | Whether to create a separate .c file for static fns. Requires nightly toolchain, and a header that actually needs this feature (otherwise bindgen won't generate the file and Bazel complains). | Boolean | optional | False |
rust_bindgen_toolchain
load("@rules_rust_bindgen//:defs.bzl", "rust_bindgen_toolchain")
rust_bindgen_toolchain(name, bindgen, clang, default_rustfmt, libclang, libstdcxx)
The tools required for the rust_bindgen rule.
This rule depends on the bindgen binary crate, and it
in turn depends on both a clang binary and the clang library. To obtain these dependencies,
rust_bindgen_dependencies imports bindgen and its dependencies.
load("@rules_rust_bindgen//:defs.bzl", "rust_bindgen_toolchain")
rust_bindgen_toolchain(
name = "bindgen_toolchain_impl",
bindgen = "//my/rust:bindgen",
clang = "//my/clang:clang",
libclang = "//my/clang:libclang.so",
libstdcxx = "//my/cpp:libstdc++",
)
toolchain(
name = "bindgen_toolchain",
toolchain = "bindgen_toolchain_impl",
toolchain_type = "@rules_rust_bindgen//:toolchain_type",
)
This toolchain will then need to be registered in the current WORKSPACE.
For additional information, see the Bazel toolchains documentation.
ATTRIBUTES
| Name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| name | A unique name for this target. | Name | required | |
| bindgen | The label of a bindgen executable. | Label | optional | None |
| clang | The label of a clang executable. | Label | optional | None |
| default_rustfmt | If set, rust_bindgen targets will always format generated sources with rustfmt. | Boolean | optional | True |
| libclang | A cc_library providing bindgen's runtime dependency on libclang. This attribute is required for hermeticity when bindgen is dynamically linked. If None, bindgen must be statically linked; else, system libraries will be used instead. | Label | optional | None |
| libstdcxx | A cc_library that satisfies libclang's libstdc++ dependency. This is used to make the execution of clang hermetic. If None, system libraries will be used instead. | Label | optional | None |
rust_bindgen_library
load("@rules_rust_bindgen//:defs.bzl", "rust_bindgen_library")
rust_bindgen_library(name, header, cc_lib, bindgen_flags, bindgen_features, clang_flags,
wrap_static_fns, **kwargs)
Generates a rust source file for header, and builds a rust_library.
Arguments are the same as rust_bindgen, and kwargs are passed directly to rust_library.
PARAMETERS