Updated rust_bindgen dependencies API (#1354)
* Moved `rust_bindgen` docs into generated stardoc
* Regenerate documentation
diff --git a/WORKSPACE.bazel b/WORKSPACE.bazel
index 8ad16b6..fef8fda 100644
--- a/WORKSPACE.bazel
+++ b/WORKSPACE.bazel
@@ -18,9 +18,11 @@
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")
diff --git a/bindgen/README.md b/bindgen/README.md
index cc0fcd2..a56d141 100644
--- a/bindgen/README.md
+++ b/bindgen/README.md
@@ -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")
-```
diff --git a/bindgen/bindgen.bzl b/bindgen/bindgen.bzl
index 28d1764..b793cd0 100644
--- a/bindgen/bindgen.bzl
+++ b/bindgen/bindgen.bzl
@@ -187,14 +187,14 @@
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 @@
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.",
diff --git a/bindgen/repositories.bzl b/bindgen/repositories.bzl
index f8614ba..c699bdc 100644
--- a/bindgen/repositories.bzl
+++ b/bindgen/repositories.bzl
@@ -18,7 +18,7 @@
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 @@
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 = "{}")
diff --git a/docs/BUILD.bazel b/docs/BUILD.bazel
index 1d1a6c1..a8e7c69 100644
--- a/docs/BUILD.bazel
+++ b/docs/BUILD.bazel
@@ -76,9 +76,11 @@
),
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",
],
diff --git a/docs/flatten.md b/docs/flatten.md
index 8428a04..fa16fc7 100644
--- a/docs/flatten.md
+++ b/docs/flatten.md
@@ -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 @@
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <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 @@
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 @@
| <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
diff --git a/docs/rust_bindgen.md b/docs/rust_bindgen.md
index 6127ede..a1ab807 100644
--- a/docs/rust_bindgen.md
+++ b/docs/rust_bindgen.md
@@ -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 @@
| :------------- | :------------- | :------------- | :------------- | :------------- |
| <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 @@
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 @@
| <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.
-
-
-
diff --git a/docs/rust_bindgen.vm b/docs/rust_bindgen.vm
new file mode 100644
index 0000000..faffca3
--- /dev/null
+++ b/docs/rust_bindgen.vm
@@ -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()
+```
+
+---
+
+---
+
+]]#
diff --git a/examples/WORKSPACE.bazel b/examples/WORKSPACE.bazel
index 8d19271..2e4482c 100644
--- a/examples/WORKSPACE.bazel
+++ b/examples/WORKSPACE.bazel
@@ -17,9 +17,11 @@
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")
