# Rust Bindgen * [rust_bindgen_library](#rust_bindgen_library) * [rust_bindgen_dependencies](#rust_bindgen_dependencies) * [rust_bindgen_register_toolchains](#rust_bindgen_register_toolchains) * [rust_bindgen_toolchain](#rust_bindgen_toolchain) * [rust_bindgen](#rust_bindgen) ## Overview These rules are for using [Bindgen][bindgen] to generate [Rust][rust] bindings to C (and some C++) libraries. [rust]: http://www.rust-lang.org/ [bindgen]: https://github.com/rust-lang/rust-bindgen See the [bindgen example](https://github.com/bazelbuild/rules_rust/tree/main/examples/ffi/rust_calling_c/simple/BUILD.bazel#L9) 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](https://bazelbuild.github.io/rules_rust/#setup)): ```python load("@rules_rust//bindgen:repositories.bzl", "rust_bindgen_dependencies", "rust_bindgen_register_toolchains") rust_bindgen_dependencies() rust_bindgen_register_toolchains() ``` --- --- ## rust_bindgen
rust_bindgen(name, bindgen_flags, cc_lib, clang_flags, header, rustfmt)
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 | optional | None | | clang_flags | Flags to pass directly to the clang executable. | List of strings | optional | [] | | header | The .h file to generate bindings for. | Label | optional | None | | rustfmt | Enable or disable running rustfmt on the generated file. | Boolean | optional | True | ## rust_bindgen_toolchain
rust_bindgen_toolchain(name, bindgen, clang, libclang, libstdcxx, rustfmt)
The tools required for the `rust_bindgen` rule. This rule depends on the [`bindgen`](https://crates.io/crates/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. ```python load("@rules_rust//bindgen:bindgen.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](https://docs.bazel.build/versions/master/toolchains.html). **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 | | 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 | | rustfmt | The label of a rustfmt executable. If this is not provided, falls back to the rust_toolchain rustfmt. | Label | optional | None | ## rust_bindgen_dependencies
rust_bindgen_dependencies()
Declare dependencies needed for bindgen. ## rust_bindgen_library
rust_bindgen_library(name, header, cc_lib, bindgen_flags, clang_flags, rustfmt, 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** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | A unique name for this target. | none | | header | The label of the .h file to generate bindings for. | none | | cc_lib | The label of the cc_library that contains the .h file. This is used to find the transitive includes. | none | | bindgen_flags | Flags to pass directly to the bindgen executable. See https://rust-lang.github.io/rust-bindgen/ for details. | None | | clang_flags | Flags to pass directly to the clang executable. | None | | rustfmt | Enable or disable running rustfmt on the generated file. | True | | kwargs | Arguments to forward to the underlying rust_library rule. | none | ## rust_bindgen_register_toolchains
rust_bindgen_register_toolchains(register_toolchains)
Registers the default toolchains for the `rules_rust` [bindgen][bg] rules. [bg]: https://rust-lang.github.io/rust-bindgen/ **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | register_toolchains | Whether or not to register toolchains. | True |