fork/rules_rust

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

UebelAndrePromoted crate_universe to non-experimental (#1504)9b61b499

0.11.0
6.1 KiB209 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    lockfile = "//:Cargo.Bazel.lock",
50    manifests = ["//:Cargo.toml"],
51)
52
53load("@crate_index//:defs.bzl", "crate_repositories")
54
55crate_repositories()
56```
57
58The generated `crates_repository` contains helper macros which make collecting dependencies for Bazel targets simpler.
59Notably, the `all_crate_deps` and `aliases` macros (see [Dependencies API](#dependencies-api)) commonly allow the
60`Cargo.toml` files to be the single source of truth for dependencies. Since these macros come from the generated
61repository, the dependencies and alias definitions they return will automatically update BUILD targets.
62
63```python
64load("@crate_index//:defs.bzl", "aliases", "all_crate_deps")
65load("@rules_rust//rust:defs.bzl", "rust_library", "rust_test")
66
67rust_library(
68    name = "lib",
69    aliases = aliases(),
70    deps = all_crate_deps(
71        normal = True,
72    ),
73    proc_macro_deps = all_crate_deps(
74        proc_macro = True,
75    ),
76)
77
78rust_test(
79    name = "unit_test",
80    crate = ":lib",
81    aliases = aliases(
82        normal_dev = True,
83        proc_macro_dev = True,
84    ),
85    deps = all_crate_deps(
86        normal_dev = True,
87    ),
88    proc_macro_deps = all_crate_deps(
89        proc_macro_dev = True,
90    ),
91)
92```
93
94### Direct Packages
95
96In cases where Rust targets have heavy interractions with other Bazel targests ([Cc][cc], [Proto][proto], etc.),
97maintaining `Cargo.toml` files may have deminishing returns as things like [rust-analyzer][ra] begin to be confused
98about missing targets or environment variables defined only in Bazel. In workspaces like this, it may be desirable
99to have a "Cargo free" setup. `crates_repository` supports this through the `packages` attribute.
100
101```python
102load("@cargo_bazel//:defs.bzl", "crate", "crates_repository", "render_config")
103
104crates_repository(
105    name = "crate_index",
106    lockfile = "//:Cargo.Bazel.lock",
107    packages = {
108        "async-trait": crate.spec(
109            version = "0.1.51",
110        ),
111        "mockall": crate.spec(
112            version = "0.10.2",
113        ),
114        "tokio": crate.spec(
115            version = "1.12.0",
116        ),
117    },
118    # Setting the default package name to `""` forces the use of the macros defined in this repository
119    # to always use the root package when looking for dependencies or aliases. This should be considered
120    # optional as the repository also exposes alises for easy access to all dependencies.
121    render_config = render_config(
122        default_package_name = ""
123    ),
124)
125
126load("@crate_index//:defs.bzl", "crate_repositories")
127
128crate_repositories()
129```
130
131Consuming dependencies may be more ergonomic in this case through the aliases defined in the new repository.
132
133```python
134load("@rules_rust//rust:defs.bzl", "rust_library", "rust_test")
135
136rust_library(
137    name = "lib",
138    deps = [
139        "@crate_index//:tokio",
140    ],
141    proc_macro_deps = [
142        "@crate_index//:async-trait",
143    ],
144)
145
146rust_test(
147    name = "unit_test",
148    crate = ":lib",
149    deps = [
150        "@crate_index//:mockall",
151    ],
152)
153```
154
155## Dependencies API
156
157After rendering dependencies, convenience macros may also be generated to provide
158convenient accessors to larger sections of the dependency graph.
159
160- [aliases](#aliases)
161- [crate_deps](#crate_deps)
162- [all_crate_deps](#all_crate_deps)
163- [crate_repositories](#crate_repositories)
164
165---
166
167---
168
169[cw]: https://doc.rust-lang.org/book/ch14-03-cargo-workspaces.html
170[cc]: https://docs.bazel.build/versions/main/be/c-cpp.html
171[proto]: https://rules-proto-grpc.com/en/latest/lang/rust.html
172[ra]: https://rust-analyzer.github.io/
173"""
174
175load(
176    "//crate_universe:defs.bzl",
177    _crate = "crate",
178    _crates_repository = "crates_repository",
179    _crates_vendor = "crates_vendor",
180    _render_config = "render_config",
181    _splicing_config = "splicing_config",
182)
183load(
184    "//crate_universe:repositories.bzl",
185    _crate_universe_dependencies = "crate_universe_dependencies",
186)
187load(
188    "//crate_universe/3rdparty/crates:defs.bzl",
189    _aliases = "aliases",
190    _all_crate_deps = "all_crate_deps",
191    _crate_deps = "crate_deps",
192    _crate_repositories = "crate_repositories",
193)
194
195# Rules
196crates_repository = _crates_repository
197crates_vendor = _crates_vendor
198
199# Utility Macros
200crate_universe_dependencies = _crate_universe_dependencies
201crate = _crate
202render_config = _render_config
203splicing_config = _splicing_config
204
205# Dependencies API
206aliases = _aliases
207all_crate_deps = _all_crate_deps
208crate_deps = _crate_deps
209crate_repositories = _crate_repositories