Updated rust_bindgen dependencies API (#1354)

* Moved `rust_bindgen` docs into generated stardoc

* Regenerate documentation
This commit is contained in:
UebelAndre 2022-05-23 07:33:51 -07:00 committed by GitHub
parent 42c4528a5f
commit 120f911d2f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 179 additions and 116 deletions

View File

@ -18,9 +18,11 @@ load("@rules_rust//proto:transitive_repositories.bzl", "rust_proto_transitive_re
rust_proto_transitive_repositories()
load("@rules_rust//bindgen:repositories.bzl", "rust_bindgen_repositories")
load("@rules_rust//bindgen:repositories.bzl", "rust_bindgen_dependencies", "rust_bindgen_register_toolchains")
rust_bindgen_repositories()
rust_bindgen_dependencies()
rust_bindgen_register_toolchains()
load("@rules_rust//tools/rust_analyzer:deps.bzl", "rust_analyzer_deps")

View File

@ -1,82 +1,8 @@
# Rust Bindgen Rules
<div class="toc">
<h2>Rules</h2>
<ul>
<li><a href="docs/index.md#rust_bindgen_toolchain">rust_bindgen_toolchain</a></li>
<li>rust_bindgen</li>
<li>rust_bindgen_library</li>
</ul>
</div>
## Overview
These rules are for using [Bindgen][bindgen] to generate [Rust][rust] bindings to C (and some C++) libraries.
See the `rules_rust` documentation for more info: https://bazelbuild.github.io/rules_rust/rust_bindgen.html
[rust]: http://www.rust-lang.org/
[bindgen]: https://github.com/rust-lang/rust-bindgen
See the [bindgen example](../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](..)):
```python
load("@rules_rust//bindgen:repositories.bzl", "rust_bindgen_repositories")
rust_bindgen_repositories()
```
This makes the default toolchain defined in [`@rules_rust`](./BUILD) available.
[raze]: https://github.com/google/cargo-raze
It will load crate dependencies of bindgen that are generated using
[cargo raze][raze] inside the rules_rust
repository. However, using those dependencies might conflict with other uses
of [cargo raze][raze]. If you need to change
those dependencies, please see the [dedicated section below](#custom-deps).
For additional information, see the [Bazel toolchains documentation](https://docs.bazel.build/versions/master/toolchains.html).
## <a name="custom-deps">Customizing dependencies
These rules 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_repositories` imports bindgen and its dependencies using BUILD files generated with
[`cargo raze`][raze], along with a tarball of clang.
If you want to change the bindgen used, or use [`cargo raze`][raze] in a more
complex scenario (with more dependencies), you must redefine those
dependencies.
To do this, once you've imported the needed dependencies (see our
[Cargo.toml](./raze/Cargo.toml) file to see the default dependencies), you
need to create your own toolchain. To do so you can create a BUILD
file with your [`rust_bindgen_toolchain`](../docs/index.md#rust_bindgen_toolchain) definition, for example:
```python
load("@rules_rust//bindgen:bindgen.bzl", "rust_bindgen_toolchain")
rust_bindgen_toolchain(
name = "bindgen-toolchain-impl",
bindgen = "//my/raze:cargo_bin_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:bindgen_toolchain",
)
```
Now that you have your own toolchain, you need to register it by
inserting the following statement in your `WORKSPACE` file:
```python
register_toolchains("//my/toolchains:bindgen-toolchain")
```

View File

@ -187,14 +187,14 @@ rust_bindgen = rule(
doc = "Flags to pass directly to the bindgen executable. See https://rust-lang.github.io/rust-bindgen/ for details.",
),
"cc_lib": attr.label(
doc = "The cc_library that contains the .h file. This is used to find the transitive includes.",
doc = "The cc_library that contains the `.h` file. This is used to find the transitive includes.",
providers = [CcInfo],
),
"clang_flags": attr.string_list(
doc = "Flags to pass directly to the clang executable.",
),
"header": attr.label(
doc = "The .h file to generate bindings for.",
doc = "The `.h` file to generate bindings for.",
allow_single_file = True,
),
"rustfmt": attr.bool(
@ -232,7 +232,34 @@ def _rust_bindgen_toolchain_impl(ctx):
rust_bindgen_toolchain = rule(
_rust_bindgen_toolchain_impl,
doc = "The tools required for the `rust_bindgen` rule.",
doc = """\
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:bindgen_toolchain",
)
```
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).
""",
attrs = {
"bindgen": attr.label(
doc = "The label of a `bindgen` executable.",

View File

@ -18,7 +18,7 @@ load("@bazel_tools//tools/build_defs/repo:utils.bzl", "maybe")
load("//bindgen/raze:crates.bzl", "rules_rust_bindgen_fetch_remote_crates")
# buildifier: disable=unnamed-macro
def rust_bindgen_repositories():
def rust_bindgen_dependencies():
"""Declare dependencies needed for bindgen."""
# nb. The bindgen rule itself should work on any platform.
@ -26,7 +26,24 @@ def rust_bindgen_repositories():
rules_rust_bindgen_fetch_remote_crates()
native.register_toolchains(str(Label("//bindgen:default_bindgen_toolchain")))
# buildifier: disable=unnamed-macro
def rust_bindgen_register_toolchains(register_toolchains = True):
"""Registers the default toolchains for the `rules_rust` [bindgen][bg] rules.
[bg]: https://rust-lang.github.io/rust-bindgen/
Args:
register_toolchains (bool, optional): Whether or not to register toolchains.
"""
if register_toolchains:
native.register_toolchains(str(Label("//bindgen:default_bindgen_toolchain")))
# buildifier: disable=unnamed-macro
def rust_bindgen_repositories():
"""**Deprecated**: Instead use [rust_bindgen_dependencies](#rust_bindgen_dependencies) and [rust_bindgen_register_toolchains](#rust_bindgen_register_toolchains)"""
rust_bindgen_dependencies()
rust_bindgen_register_toolchains()
_COMMON_WORKSPACE = """\
workspace(name = "{}")

View File

@ -76,9 +76,11 @@ PAGES = dict([
),
page(
name = "rust_bindgen",
header_template = ":rust_bindgen.vm",
symbols = [
"rust_bindgen_library",
"rust_bindgen_repositories",
"rust_bindgen_dependencies",
"rust_bindgen_register_toolchains",
"rust_bindgen_toolchain",
"rust_bindgen",
],

View File

@ -16,8 +16,9 @@
* [rust_analyzer_aspect](#rust_analyzer_aspect)
* [rust_binary](#rust_binary)
* [rust_bindgen](#rust_bindgen)
* [rust_bindgen_dependencies](#rust_bindgen_dependencies)
* [rust_bindgen_library](#rust_bindgen_library)
* [rust_bindgen_repositories](#rust_bindgen_repositories)
* [rust_bindgen_register_toolchains](#rust_bindgen_register_toolchains)
* [rust_bindgen_toolchain](#rust_bindgen_toolchain)
* [rust_clippy](#rust_clippy)
* [rust_clippy_aspect](#rust_clippy_aspect)
@ -317,9 +318,9 @@ Generates a rust source file from a cc_library and a header.
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="rust_bindgen-name"></a>name | A unique name for this target. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | |
| <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 | [] |
| <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/docs/build-ref.html#labels">Label</a> | optional | None |
| <a id="rust_bindgen-cc_lib"></a>cc_lib | The cc_library that contains the <code>.h</code> file. This is used to find the transitive includes. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
| <a id="rust_bindgen-clang_flags"></a>clang_flags | Flags to pass directly to the clang executable. | List of strings | optional | [] |
| <a id="rust_bindgen-header"></a>header | The .h file to generate bindings for. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
| <a id="rust_bindgen-header"></a>header | The <code>.h</code> file to generate bindings for. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
| <a id="rust_bindgen-rustfmt"></a>rustfmt | Enable or disable running rustfmt on the generated file. | Boolean | optional | True |
@ -333,6 +334,32 @@ rust_bindgen_toolchain(<a href="#rust_bindgen_toolchain-name">name</a>, <a href=
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:bindgen_toolchain",
)
```
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**
@ -1540,18 +1567,6 @@ Arguments are the same as `rust_bindgen`, and `kwargs` are passed directly to ru
| <a id="rust_bindgen_library-kwargs"></a>kwargs | Arguments to forward to the underlying <code>rust_library</code> rule. | none |
<a id="#rust_bindgen_repositories"></a>
## rust_bindgen_repositories
<pre>
rust_bindgen_repositories()
</pre>
Declare dependencies needed for bindgen.
<a id="#rust_proto_repositories"></a>
## rust_proto_repositories

View File

@ -2,10 +2,40 @@
# Rust Bindgen
* [rust_bindgen_library](#rust_bindgen_library)
* [rust_bindgen_repositories](#rust_bindgen_repositories)
* [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()
```
---
---
<a id="#rust_bindgen"></a>
## rust_bindgen
@ -23,9 +53,9 @@ Generates a rust source file from a cc_library and a header.
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <a id="rust_bindgen-name"></a>name | A unique name for this target. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | |
| <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 | [] |
| <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/docs/build-ref.html#labels">Label</a> | optional | None |
| <a id="rust_bindgen-cc_lib"></a>cc_lib | The cc_library that contains the <code>.h</code> file. This is used to find the transitive includes. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
| <a id="rust_bindgen-clang_flags"></a>clang_flags | Flags to pass directly to the clang executable. | List of strings | optional | [] |
| <a id="rust_bindgen-header"></a>header | The .h file to generate bindings for. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
| <a id="rust_bindgen-header"></a>header | The <code>.h</code> file to generate bindings for. | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
| <a id="rust_bindgen-rustfmt"></a>rustfmt | Enable or disable running rustfmt on the generated file. | Boolean | optional | True |
@ -39,6 +69,32 @@ rust_bindgen_toolchain(<a href="#rust_bindgen_toolchain-name">name</a>, <a href=
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:bindgen_toolchain",
)
```
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**
@ -79,15 +135,3 @@ Arguments are the same as `rust_bindgen`, and `kwargs` are passed directly to ru
| <a id="rust_bindgen_library-kwargs"></a>kwargs | Arguments to forward to the underlying <code>rust_library</code> rule. | none |
<a id="#rust_bindgen_repositories"></a>
## rust_bindgen_repositories
<pre>
rust_bindgen_repositories()
</pre>
Declare dependencies needed for bindgen.

28
docs/rust_bindgen.vm Normal file
View File

@ -0,0 +1,28 @@
#[[
## 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()
```
---
---
]]#

View File

@ -17,9 +17,11 @@ rust_register_toolchains(
include_rustc_srcs = True,
)
load("@rules_rust//bindgen:repositories.bzl", "rust_bindgen_repositories")
load("@rules_rust//bindgen:repositories.bzl", "rust_bindgen_dependencies", "rust_bindgen_register_toolchains")
rust_bindgen_repositories()
rust_bindgen_dependencies()
rust_bindgen_register_toolchains()
load("@rules_rust//proto:repositories.bzl", "rust_proto_repositories")