Rust Bindgen
- rust_bindgen_library
- rust_bindgen
- rust_bindgen_toolchain
- rust_bindgen_dependencies
- rust_bindgen_register_toolchains
Overview
These rules are for using Bindgen to generate Rust bindings to C (and some C++) libraries.
See the bindgen example for a more complete example of use.
Setup
To use the Rust bindgen rules, add the following to your WORKSPACE
file to add the
external repositories for the Rust bindgen toolchain (in addition to the rust rules setup):
load("@rules_rust//bindgen:repositories.bzl", "rust_bindgen_dependencies", "rust_bindgen_register_toolchains")
rust_bindgen_dependencies()
rust_bindgen_register_toolchains()
load("@rules_rust//bindgen:transitive_repositories.bzl", "rust_bindgen_transitive_dependencies")
rust_bindgen_transitive_dependencies()
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 then no Bindgen related calls should be added to your WORKSPACE and instead
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
rust_bindgen(name, bindgen_flags, cc_lib, clang_flags, header, 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 | |
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
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 that provides bindgen's runtime dependency on libclang. | 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_dependencies
rust_bindgen_dependencies()
Declare dependencies needed for bindgen.
RETURNS
list[struct(repo=str, is_dev_dep=bool)]: A list of the repositories defined by this macro.
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
rust_bindgen_register_toolchains
rust_bindgen_register_toolchains(register_toolchains)
Registers the default toolchains for the rules_rust
bindgen rules.
PARAMETERS