1<!-- Generated with Stardoc: http://skydoc.bazel.build --> 2# Rust Bindgen 3 4* [rust_bindgen_library](#rust_bindgen_library) 5* [rust_bindgen](#rust_bindgen) 6* [rust_bindgen_toolchain](#rust_bindgen_toolchain) 7* [rust_bindgen_dependencies](#rust_bindgen_dependencies) 8* [rust_bindgen_register_toolchains](#rust_bindgen_register_toolchains) 9 10 11## Overview 12 13These rules are for using [Bindgen][bindgen] to generate [Rust][rust] bindings to C (and some C++) libraries. 14 15[rust]: http://www.rust-lang.org/ 16[bindgen]: https://github.com/rust-lang/rust-bindgen 17 18See the [bindgen example](https://github.com/bazelbuild/rules_rust/tree/main/examples/bindgen/BUILD.bazel) for a more complete example of use. 19 20### Setup 21 22To use the Rust bindgen rules, add the following to your `WORKSPACE` file to add the 23external repositories for the Rust bindgen toolchain (in addition to the [rust rules setup](https://bazelbuild.github.io/rules_rust/#setup)): 24 25```python 26load("@rules_rust//bindgen:repositories.bzl", "rust_bindgen_dependencies", "rust_bindgen_register_toolchains") 27 28rust_bindgen_dependencies() 29 30rust_bindgen_register_toolchains() 31 32load("@rules_rust//bindgen:transitive_repositories.bzl", "rust_bindgen_transitive_dependencies") 33 34rust_bindgen_transitive_dependencies() 35``` 36 37Bindgen aims to be as hermetic as possible so will end up building `libclang` from [llvm-project][llvm_proj] from 38source. If this is found to be undesirable then no Bindgen related calls should be added to your WORKSPACE and instead 39users should define their own repositories using something akin to [crate_universe][cra_uni] and define their own 40toolchains following the instructions for [rust_bindgen_toolchain](#rust_bindgen_toolchain). 41 42[llvm_proj]: https://github.com/llvm/llvm-project 43[cra_uni]: https://bazelbuild.github.io/rules_rust/crate_universe.html 44 45--- 46 47--- 48 49 50 51<a id="rust_bindgen"></a> 52 53## rust_bindgen 54 55<pre> 56rust_bindgen(<a href="#rust_bindgen-name">name</a>, <a href="#rust_bindgen-bindgen_flags">bindgen_flags</a>, <a href="#rust_bindgen-cc_lib">cc_lib</a>, <a href="#rust_bindgen-clang_flags">clang_flags</a>, <a href="#rust_bindgen-header">header</a>, <a href="#rust_bindgen-wrap_static_fns">wrap_static_fns</a>) 57</pre> 58 59Generates a rust source file from a cc_library and a header. 60 61**ATTRIBUTES** 62 63 64| Name | Description | Type | Mandatory | Default | 65| :------------- | :------------- | :------------- | :------------- | :------------- | 66| <a id="rust_bindgen-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | 67| <a id="rust_bindgen-bindgen_flags"></a>bindgen_flags | Flags to pass directly to the bindgen executable. See https://rust-lang.github.io/rust-bindgen/ for details. | List of strings | optional | `[]` | 68| <a id="rust_bindgen-cc_lib"></a>cc_lib | The cc_library that contains the `.h` file. This is used to find the transitive includes. | <a href="https://bazel.build/concepts/labels">Label</a> | required | | 69| <a id="rust_bindgen-clang_flags"></a>clang_flags | Flags to pass directly to the clang executable. | List of strings | optional | `[]` | 70| <a id="rust_bindgen-header"></a>header | The `.h` file to generate bindings for. | <a href="https://bazel.build/concepts/labels">Label</a> | required | | 71| <a id="rust_bindgen-wrap_static_fns"></a>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` | 72 73 74<a id="rust_bindgen_toolchain"></a> 75 76## rust_bindgen_toolchain 77 78<pre> 79rust_bindgen_toolchain(<a href="#rust_bindgen_toolchain-name">name</a>, <a href="#rust_bindgen_toolchain-bindgen">bindgen</a>, <a href="#rust_bindgen_toolchain-clang">clang</a>, <a href="#rust_bindgen_toolchain-default_rustfmt">default_rustfmt</a>, <a href="#rust_bindgen_toolchain-libclang">libclang</a>, <a href="#rust_bindgen_toolchain-libstdcxx">libstdcxx</a>) 80</pre> 81 82The tools required for the `rust_bindgen` rule. 83 84This rule depends on the [`bindgen`](https://crates.io/crates/bindgen) binary crate, and it 85in turn depends on both a clang binary and the clang library. To obtain these dependencies, 86`rust_bindgen_dependencies` imports bindgen and its dependencies. 87 88```python 89load("@rules_rust//bindgen:defs.bzl", "rust_bindgen_toolchain") 90 91rust_bindgen_toolchain( 92 name = "bindgen_toolchain_impl", 93 bindgen = "//my/rust:bindgen", 94 clang = "//my/clang:clang", 95 libclang = "//my/clang:libclang.so", 96 libstdcxx = "//my/cpp:libstdc++", 97) 98 99toolchain( 100 name = "bindgen_toolchain", 101 toolchain = "bindgen_toolchain_impl", 102 toolchain_type = "@rules_rust//bindgen:toolchain_type", 103) 104``` 105 106This toolchain will then need to be registered in the current `WORKSPACE`. 107For additional information, see the [Bazel toolchains documentation](https://docs.bazel.build/versions/master/toolchains.html). 108 109**ATTRIBUTES** 110 111 112| Name | Description | Type | Mandatory | Default | 113| :------------- | :------------- | :------------- | :------------- | :------------- | 114| <a id="rust_bindgen_toolchain-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | 115| <a id="rust_bindgen_toolchain-bindgen"></a>bindgen | The label of a `bindgen` executable. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` | 116| <a id="rust_bindgen_toolchain-clang"></a>clang | The label of a `clang` executable. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` | 117| <a id="rust_bindgen_toolchain-default_rustfmt"></a>default_rustfmt | If set, `rust_bindgen` targets will always format generated sources with `rustfmt`. | Boolean | optional | `True` | 118| <a id="rust_bindgen_toolchain-libclang"></a>libclang | A cc_library that provides bindgen's runtime dependency on libclang. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` | 119| <a id="rust_bindgen_toolchain-libstdcxx"></a>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. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` | 120 121 122<a id="rust_bindgen_dependencies"></a> 123 124## rust_bindgen_dependencies 125 126<pre> 127rust_bindgen_dependencies() 128</pre> 129 130Declare dependencies needed for bindgen. 131 132 133**RETURNS** 134 135list[struct(repo=str, is_dev_dep=bool)]: A list of the repositories 136 defined by this macro. 137 138 139<a id="rust_bindgen_library"></a> 140 141## rust_bindgen_library 142 143<pre> 144rust_bindgen_library(<a href="#rust_bindgen_library-name">name</a>, <a href="#rust_bindgen_library-header">header</a>, <a href="#rust_bindgen_library-cc_lib">cc_lib</a>, <a href="#rust_bindgen_library-bindgen_flags">bindgen_flags</a>, <a href="#rust_bindgen_library-bindgen_features">bindgen_features</a>, <a href="#rust_bindgen_library-clang_flags">clang_flags</a>, 145 <a href="#rust_bindgen_library-wrap_static_fns">wrap_static_fns</a>, <a href="#rust_bindgen_library-kwargs">kwargs</a>) 146</pre> 147 148Generates a rust source file for `header`, and builds a rust_library. 149 150Arguments are the same as `rust_bindgen`, and `kwargs` are passed directly to rust_library. 151 152 153**PARAMETERS** 154 155 156| Name | Description | Default Value | 157| :------------- | :------------- | :------------- | 158| <a id="rust_bindgen_library-name"></a>name | A unique name for this target. | none | 159| <a id="rust_bindgen_library-header"></a>header | The label of the .h file to generate bindings for. | none | 160| <a id="rust_bindgen_library-cc_lib"></a>cc_lib | The label of the cc_library that contains the .h file. This is used to find the transitive includes. | none | 161| <a id="rust_bindgen_library-bindgen_flags"></a>bindgen_flags | Flags to pass directly to the bindgen executable. See https://rust-lang.github.io/rust-bindgen/ for details. | `None` | 162| <a id="rust_bindgen_library-bindgen_features"></a>bindgen_features | The `features` attribute for the `rust_bindgen` target. | `None` | 163| <a id="rust_bindgen_library-clang_flags"></a>clang_flags | Flags to pass directly to the clang executable. | `None` | 164| <a id="rust_bindgen_library-wrap_static_fns"></a>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", | `False` | 165| <a id="rust_bindgen_library-kwargs"></a>kwargs | Arguments to forward to the underlying `rust_library` rule. | none | 166 167 168<a id="rust_bindgen_register_toolchains"></a> 169 170## rust_bindgen_register_toolchains 171 172<pre> 173rust_bindgen_register_toolchains(<a href="#rust_bindgen_register_toolchains-register_toolchains">register_toolchains</a>) 174</pre> 175 176Registers the default toolchains for the `rules_rust` [bindgen][bg] rules. 177 178[bg]: https://rust-lang.github.io/rust-bindgen/ 179 180 181**PARAMETERS** 182 183 184| Name | Description | Default Value | 185| :------------- | :------------- | :------------- | 186| <a id="rust_bindgen_register_toolchains-register_toolchains"></a>register_toolchains | Whether or not to register toolchains. | `True` | 187 188 189