mirror of https://github.com/bazelbuild/rules_rust
Updated rust_bindgen dependencies API (#1354)
* Moved `rust_bindgen` docs into generated stardoc * Regenerate documentation
This commit is contained in:
UebelAndre
GitHub
parent
42c4528a5f
commit
120f911d2f
|
|
@ -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")
|
||||
|
||||
|
|
|
|||
|
|
@ -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")
|
||||
```
|
||||
|
|
|
|||
|
|
@ -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.",
|
||||
|
|
|
|||
|
|
@ -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 = "{}")
|
||||
|
|
|
|||
|
|
@ -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",
|
||||
],
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
]]#
|
||||
|
|
@ -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")
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue