fork/rules_rust

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

UebelAndrecrate_universe: Improved documentation (#1305)42f78f25

0.8.1
6.3 KiB213 linesraw
1"""# Crate Universe
2
3Crate Universe is a set of Bazel rule for generating Rust targets using Cargo.
4
5## Experimental
6
7`crate_universe` is experimental, and may have breaking API changes at any time. These instructions may also change without notice.
8
9## Setup
10
11After loading `rules_rust` in your workspace, set the following to begin using `crate_universe`:
12
13```python
14load("@rules_rust//crate_universe:repositories.bzl", "crate_universe_dependencies")
15
16crate_universe_dependencies()
17```
18
19Note that if the current version of `rules_rust` is not a release artifact, you may need to set additional
20flags such as [`bootstrap = True`](#crate_universe_dependencies-bootstrap) on the `crate_universe_dependencies`
21call above or [crates_repository::generator_urls](#crates_repository-generator_urls) in uses of `crates_repository`.
22
23## Rules
24
25- [crates_repository](#crates_repository)
26- [crates_vendor](#crates_vendor)
27
28## Utility Macros
29
30- [crate_universe_dependencies](#crate_universe_dependencies)
31- [crate.annotation](#crateannotation)
32- [crate.spec](#cratespec)
33- [crate.workspace_member](#crateworkspace_member)
34- [render_config](#render_config)
35- [splicing_config](#splicing_config)
36
37## Workflows
38
39The [`crates_repository`](#crates_repository) rule (the primary repository rule of `rules_rust`'s cargo support) supports a number of different
40ways users can express and organize their dependencies. The most common are listed below though there are more to be found in
41the [./examples/crate_universe](https://github.com/bazelbuild/rules_rust/tree/main/examples/crate_universe) directory.
42
43### Cargo Workspaces
44
45One of the simpler ways to wire up dependencies would be to first structure your project into a [Cargo workspace][cw].
46The `crates_repository` rule can ingest a root `Cargo.toml` file and generate dependencies from there.
47
48```python
49load("@rules_rust//crate_universe:defs.bzl", "crates_repository")
50
51crates_repository(
52    name = "crate_index",
53    lockfile = "//:Cargo.Bazel.lock",
54    manifests = ["//:Cargo.toml"],
55)
56
57load("@crate_index//:defs.bzl", "crate_repositories")
58
59crate_repositories()
60```
61
62The generated `crates_repository` contains helper macros which make collecting dependencies for Bazel targets simpler.
63Notably, the `all_crate_deps` and `aliases` macros (see [Dependencies API](#dependencies-api)) commonly allow the
64`Cargo.toml` files to be the single source of truth for dependencies. Since these macros come from the generated
65repository, the dependencies and alias definitions they return will automatically update BUILD targets.
66
67```python
68load("@crate_index//:defs.bzl", "aliases", "all_crate_deps")
69load("@rules_rust//rust:defs.bzl", "rust_library", "rust_test")
70
71rust_library(
72    name = "lib",
73    aliases = aliases(),
74    deps = all_crate_deps(
75        normal = True,
76    ),
77    proc_macro_deps = all_crate_deps(
78        proc_macro = True,
79    ),
80)
81
82rust_test(
83    name = "unit_test",
84    crate = ":lib",
85    aliases = aliases(
86        normal_dev = True,
87        proc_macro_dev = True,
88    ),
89    deps = all_crate_deps(
90        normal_dev = True,
91    ),
92    proc_macro_deps = all_crate_deps(
93        proc_macro_dev = True,
94    ),
95)
96```
97
98### Direct Packages
99
100In cases where Rust targets have heavy interractions with other Bazel targests ([Cc][cc], [Proto][proto], etc.),
101maintaining `Cargo.toml` files may have deminishing returns as things like [rust-analyzer][ra] begin to be confused
102about missing targets or environment variables defined only in Bazel. In workspaces like this, it may be desirable
103to have a "Cargo free" setup. `crates_repository` supports this through the `packages` attribute.
104
105```python
106load("@cargo_bazel//:defs.bzl", "crate", "crates_repository", "render_config")
107
108crates_repository(
109    name = "crate_index",
110    lockfile = "//:Cargo.Bazel.lock",
111    packages = {
112        "async-trait": crate.spec(
113            version = "0.1.51",
114        ),
115        "mockall": crate.spec(
116            version = "0.10.2",
117        ),
118        "tokio": crate.spec(
119            version = "1.12.0",
120        ),
121    },
122    # Setting the default package name to `""` forces the use of the macros defined in this repository
123    # to always use the root package when looking for dependencies or aliases. This should be considered
124    # optional as the repository also exposes alises for easy access to all dependencies.
125    render_config = render_config(
126        default_package_name = ""
127    ),
128)
129
130load("@crate_index//:defs.bzl", "crate_repositories")
131
132crate_repositories()
133```
134
135Consuming dependencies may be more ergonomic in this case through the aliases defined in the new repository.
136
137```python
138load("@rules_rust//rust:defs.bzl", "rust_library", "rust_test")
139
140rust_library(
141    name = "lib",
142    deps = [
143        "@crate_index//:tokio",
144    ],
145    proc_macro_deps = [
146        "@crate_index//:async-trait",
147    ],
148)
149
150rust_test(
151    name = "unit_test",
152    crate = ":lib",
153    deps = [
154        "@crate_index//:mockall",
155    ],
156)
157```
158
159## Dependencies API
160
161After rendering dependencies, convenience macros may also be generated to provide
162convenient accessors to larger sections of the dependency graph.
163
164- [aliases](#aliases)
165- [crate_deps](#crate_deps)
166- [all_crate_deps](#all_crate_deps)
167- [crate_repositories](#crate_repositories)
168
169---
170
171---
172
173[cw]: https://doc.rust-lang.org/book/ch14-03-cargo-workspaces.html
174[cc]: https://docs.bazel.build/versions/main/be/c-cpp.html
175[proto]: https://rules-proto-grpc.com/en/latest/lang/rust.html
176[ra]: https://rust-analyzer.github.io/
177"""
178
179load(
180    "//crate_universe:defs.bzl",
181    _crate = "crate",
182    _crates_repository = "crates_repository",
183    _crates_vendor = "crates_vendor",
184    _render_config = "render_config",
185    _splicing_config = "splicing_config",
186)
187load(
188    "//crate_universe:repositories.bzl",
189    _crate_universe_dependencies = "crate_universe_dependencies",
190)
191load(
192    "//crate_universe/3rdparty/crates:defs.bzl",
193    _aliases = "aliases",
194    _all_crate_deps = "all_crate_deps",
195    _crate_deps = "crate_deps",
196    _crate_repositories = "crate_repositories",
197)
198
199# Rules
200crates_repository = _crates_repository
201crates_vendor = _crates_vendor
202
203# Utility Macros
204crate_universe_dependencies = _crate_universe_dependencies
205crate = _crate
206render_config = _render_config
207splicing_config = _splicing_config
208
209# Dependencies API
210aliases = _aliases
211all_crate_deps = _all_crate_deps
212crate_deps = _crate_deps
213crate_repositories = _crate_repositories