Skip to content

Commit 5e426fa

Browse files
authored
Add documentation about using binary dependencies in crate_universe (#3183)
I spent a bit of time with it on how to use it properly as the documentation was not too explicit to me. So I thought I write it down.
1 parent c241ed0 commit 5e426fa

File tree

1 file changed

+43
-2
lines changed

1 file changed

+43
-2
lines changed

crate_universe/extensions.bzl

+43-2
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ There are some examples of using crate_universe with bzlmod in the [example fold
1414
2. [Dependencies](#dependencies)
1515
* [Cargo Workspace](#cargo-workspaces)
1616
* [Direct Packages](#direct-dependencies)
17+
* [Binary Dependencies](#binary-dependencies)
1718
* [Vendored Dependencies](#vendored-dependencies)
1819
3. [Crate reference](#crate)
1920
* [from_cargo](#from_cargo)
@@ -45,7 +46,8 @@ There are three different ways to declare dependencies in your MODULE.
4546
4647
1) Cargo workspace
4748
2) Direct Dependencies
48-
3) Vendored Dependencies
49+
3) Binary Dependencies
50+
4) Vendored Dependencies
4951
5052
### Cargo Workspaces
5153
@@ -136,7 +138,7 @@ For more details about repin, [please refer to the documentation](https://bazelb
136138
In cases where Rust targets have heavy interactions with other Bazel targets ([Cc](https://docs.bazel.build/versions/main/be/c-cpp.html), [Proto](https://rules-proto-grpc.com/en/4.5.0/lang/rust.html),
137139
etc.), maintaining Cargo.toml files may have diminishing returns as things like rust-analyzer
138140
begin to be confused about missing targets or environment variables defined only in Bazel.
139-
In situations like this, it may be desirable to have a Cargo free setup. You find an example in the in the [example folder](../examples/bzlmod/hello_world_no_cargo).
141+
In situations like this, it may be desirable to have a "Cargo free" setup. You find an example in the in the [example folder](../examples/bzlmod/hello_world_no_cargo).
140142
141143
crates_repository supports this through the packages attribute,
142144
as shown below.
@@ -175,6 +177,45 @@ rust_binary(
175177
Notice, direct dependencies do not need repining.
176178
Only a cargo workspace needs updating whenever the underlying Cargo.toml file changed.
177179
180+
### Binary Dependencies
181+
182+
With cargo you `can install` binary dependencies (bindeps) as well with `cargo install` command.
183+
184+
We don't have such easy facilities available in bazel besides specifying it as a dependency.
185+
To mimic cargo's bindeps feature we use the unstable feature called [artifact-dependencies](https://doc.rust-lang.org/nightly/cargo/reference/unstable.html?highlight=feature#artifact-dependencies)
186+
which integrates well with bazel concepts.
187+
188+
You could use the syntax specified in the above document to place it in `Cargo.toml`. For that you can consult the following [example](https://github.com/bazelbuild/rules_rust/blob/main/examples/crate_universe/MODULE.bazel#L279-L291).
189+
190+
This method has the following consequences:
191+
* if you use shared dependency tree with your project these binary dependencies will interfere with yours (may conflict)
192+
* you have to use nightly `host_tools_repo` to generate dependencies because
193+
194+
Alternatively you can specify this in a separate `repo` with `cargo.from_specs` syntax:
195+
196+
```python
197+
bindeps = use_extension("@rules_rust//crate_universe:extension.bzl", "crate")
198+
199+
bindeps.spec(package = "cargo-machete", version = "=0.7.0", artifact = "bin")
200+
bindeps.annotation(crate = "cargo-machete", gen_all_binaries = True)
201+
202+
bindeps.from_specs(
203+
name = "bindeps",
204+
host_tools_repo = "rust_host_tools_nightly",
205+
)
206+
207+
use_repo(bindeps, "bindeps")
208+
```
209+
210+
You can run the specified binary dependency with the following command or create additional more complex rules on top of it.
211+
212+
```bash
213+
bazel run @bindeps//:cargo-machete__cargo-machete
214+
```
215+
216+
Notice, direct dependencies do not need repining.
217+
Only a cargo workspace needs updating whenever the underlying Cargo.toml file changed.
218+
178219
### Vendored Dependencies
179220
180221
In some cases, it is require that all external dependencies are vendored, meaning downloaded

0 commit comments

Comments
 (0)