fork/rules_rust

git clone https://git.julia.blue/fork/rules_rust

David TolnayAdd gen_binaries annotation to control which bins to make target for (#1718)36b57af7

rust-analyzer
8.6 KiB294 linesraw
1"""# Crate Universe
2
3Crate Universe is a set of Bazel rule for generating Rust targets using Cargo.
4
5## Setup
6
7After loading `rules_rust` in your workspace, set the following to begin using `crate_universe`:
8
9```python
10load("@rules_rust//crate_universe:repositories.bzl", "crate_universe_dependencies")
11
12crate_universe_dependencies()
13```
14
15Note that if the current version of `rules_rust` is not a release artifact, you may need to set additional
16flags such as [`bootstrap = True`](#crate_universe_dependencies-bootstrap) on the `crate_universe_dependencies`
17call above or [crates_repository::generator_urls](#crates_repository-generator_urls) in uses of `crates_repository`.
18
19## Rules
20
21- [crates_repository](#crates_repository)
22- [crates_vendor](#crates_vendor)
23
24## Utility Macros
25
26- [crate_universe_dependencies](#crate_universe_dependencies)
27- [crate.annotation](#crateannotation)
28- [crate.spec](#cratespec)
29- [crate.workspace_member](#crateworkspace_member)
30- [render_config](#render_config)
31- [splicing_config](#splicing_config)
32
33## Workflows
34
35The [`crates_repository`](#crates_repository) rule (the primary repository rule of `rules_rust`'s cargo support) supports a number of different
36ways users can express and organize their dependencies. The most common are listed below though there are more to be found in
37the [./examples/crate_universe](https://github.com/bazelbuild/rules_rust/tree/main/examples/crate_universe) directory.
38
39### Cargo Workspaces
40
41One of the simpler ways to wire up dependencies would be to first structure your project into a [Cargo workspace][cw].
42The `crates_repository` rule can ingest a root `Cargo.toml` file and generate dependencies from there.
43
44```python
45load("@rules_rust//crate_universe:defs.bzl", "crates_repository")
46
47crates_repository(
48    name = "crate_index",
49    cargo_lockfile = "//:Cargo.lock",
50    lockfile = "//:Cargo.Bazel.lock",
51    manifests = ["//:Cargo.toml"],
52)
53
54load("@crate_index//:defs.bzl", "crate_repositories")
55
56crate_repositories()
57```
58
59The generated `crates_repository` contains helper macros which make collecting dependencies for Bazel targets simpler.
60Notably, the `all_crate_deps` and `aliases` macros (see [Dependencies API](#dependencies-api)) commonly allow the
61`Cargo.toml` files to be the single source of truth for dependencies. Since these macros come from the generated
62repository, the dependencies and alias definitions they return will automatically update BUILD targets.
63
64```python
65load("@crate_index//:defs.bzl", "aliases", "all_crate_deps")
66load("@rules_rust//rust:defs.bzl", "rust_library", "rust_test")
67
68rust_library(
69    name = "lib",
70    aliases = aliases(),
71    deps = all_crate_deps(
72        normal = True,
73    ),
74    proc_macro_deps = all_crate_deps(
75        proc_macro = True,
76    ),
77)
78
79rust_test(
80    name = "unit_test",
81    crate = ":lib",
82    aliases = aliases(
83        normal_dev = True,
84        proc_macro_dev = True,
85    ),
86    deps = all_crate_deps(
87        normal_dev = True,
88    ),
89    proc_macro_deps = all_crate_deps(
90        proc_macro_dev = True,
91    ),
92)
93```
94
95### Direct Packages
96
97In cases where Rust targets have heavy interractions with other Bazel targests ([Cc][cc], [Proto][proto], etc.),
98maintaining `Cargo.toml` files may have deminishing returns as things like [rust-analyzer][ra] begin to be confused
99about missing targets or environment variables defined only in Bazel. In workspaces like this, it may be desirable
100to have a "Cargo free" setup. `crates_repository` supports this through the `packages` attribute.
101
102```python
103load("@rules_rust//crate_universe:defs.bzl", "crate", "crates_repository", "render_config")
104
105crates_repository(
106    name = "crate_index",
107    cargo_lockfile = "//:Cargo.lock",
108    lockfile = "//:Cargo.Bazel.lock",
109    packages = {
110        "async-trait": crate.spec(
111            version = "0.1.51",
112        ),
113        "mockall": crate.spec(
114            version = "0.10.2",
115        ),
116        "tokio": crate.spec(
117            version = "1.12.0",
118        ),
119    },
120    # Setting the default package name to `""` forces the use of the macros defined in this repository
121    # to always use the root package when looking for dependencies or aliases. This should be considered
122    # optional as the repository also exposes alises for easy access to all dependencies.
123    render_config = render_config(
124        default_package_name = ""
125    ),
126)
127
128load("@crate_index//:defs.bzl", "crate_repositories")
129
130crate_repositories()
131```
132
133Consuming dependencies may be more ergonomic in this case through the aliases defined in the new repository.
134
135```python
136load("@rules_rust//rust:defs.bzl", "rust_library", "rust_test")
137
138rust_library(
139    name = "lib",
140    deps = [
141        "@crate_index//:tokio",
142    ],
143    proc_macro_deps = [
144        "@crate_index//:async-trait",
145    ],
146)
147
148rust_test(
149    name = "unit_test",
150    crate = ":lib",
151    deps = [
152        "@crate_index//:mockall",
153    ],
154)
155```
156
157### Binary dependencies
158
159Neither of the above approaches supports depending on binary-only packages.
160
161In order to depend on a Cargo package that contains binaries and no library, you
162will need to do one of the following:
163
164- Fork the package to add an empty lib.rs, which makes the package visible to
165  Cargo metadata and compatible with the above approaches;
166
167- Or handwrite your own build target for the binary, use `http_archive` to
168  import its source code, and use `crates_repository` to make build targets for
169  its dependencies. This is demonstrated below using the `rustfilt` crate as an
170  example.
171
172```python
173# in WORKSPACE.bazel
174
175load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
176
177http_archive(
178    name = "rustfilt",
179    build_file = "//rustfilt:BUILD.rustfilt.bazel",
180    sha256 = "c8d748b182c8f95224336d20dcc5609598af612581ce60cfb29da4dc8d0091f2",
181    strip_prefix = "rustfilt-0.2.1",
182    type = "tar.gz",
183    urls = ["https://crates.io/api/v1/crates/rustfilt/0.2.1/download"],
184)
185
186load("@rules_rust//crate_universe:defs.bzl", "crates_repository")
187
188crates_repository(
189    name = "rustfilt_deps",
190    cargo_lockfile = "//rustfilt:Cargo.lock",
191    manifests = ["@rustfilt//:Cargo.toml"],
192)
193
194load("@rustfilt_deps//:defs.bzl", rustfilt_deps = "crate_repositories")
195
196rustfilt_deps()
197```
198
199```python
200# in rustfilt/BUILD.rustfilt.bazel
201
202load("@rules_rust//rust:defs.bzl", "rust_binary")
203
204rust_binary(
205    name = "rustfilt",
206    srcs = glob(["src/**/*.rs"]),
207    edition = "2018",
208    deps = [
209        "@rustfilt_deps//:clap",
210        "@rustfilt_deps//:lazy_static",
211        "@rustfilt_deps//:regex",
212        "@rustfilt_deps//:rustc-demangle",
213    ],
214)
215```
216
217If you use either `crates_repository` or `crates_vendor` to depend on a Cargo
218package that contains _both_ a library crate _and_ binaries, by default only the
219library gets made available to Bazel. To generate Bazel targets for the binary
220crates as well, you must opt in to it with an annotation on the package:
221
222```python
223load("@rules_rust//crate_universe:defs.bzl", "crates_repository", "crate")
224
225crates_repository(
226    name = "crate_index",
227    annotations = {
228        "thepackage": [crate.annotation(
229            gen_binaries = True,
230            # Or, to expose just a subset of the package's binaries by name:
231            gen_binaries = ["rustfilt"],
232        )],
233    },
234    # Or, to expose every binary of every package:
235    generate_binaries = True,
236    ...
237)
238```
239
240## Dependencies API
241
242After rendering dependencies, convenience macros may also be generated to provide
243convenient accessors to larger sections of the dependency graph.
244
245- [aliases](#aliases)
246- [crate_deps](#crate_deps)
247- [all_crate_deps](#all_crate_deps)
248- [crate_repositories](#crate_repositories)
249
250---
251
252---
253
254[cw]: https://doc.rust-lang.org/book/ch14-03-cargo-workspaces.html
255[cc]: https://docs.bazel.build/versions/main/be/c-cpp.html
256[proto]: https://rules-proto-grpc.com/en/latest/lang/rust.html
257[ra]: https://rust-analyzer.github.io/
258"""
259
260load(
261    "//crate_universe:defs.bzl",
262    _crate = "crate",
263    _crates_repository = "crates_repository",
264    _crates_vendor = "crates_vendor",
265    _render_config = "render_config",
266    _splicing_config = "splicing_config",
267)
268load(
269    "//crate_universe:repositories.bzl",
270    _crate_universe_dependencies = "crate_universe_dependencies",
271)
272load(
273    "//crate_universe/3rdparty/crates:defs.bzl",
274    _aliases = "aliases",
275    _all_crate_deps = "all_crate_deps",
276    _crate_deps = "crate_deps",
277    _crate_repositories = "crate_repositories",
278)
279
280# Rules
281crates_repository = _crates_repository
282crates_vendor = _crates_vendor
283
284# Utility Macros
285crate_universe_dependencies = _crate_universe_dependencies
286crate = _crate
287render_config = _render_config
288splicing_config = _splicing_config
289
290# Dependencies API
291aliases = _aliases
292all_crate_deps = _all_crate_deps
293crate_deps = _crate_deps
294crate_repositories = _crate_repositories