fork/rules_rust
git clone https://git.julia.blue/fork/rules_rust
36b57af7
rust-analyzer
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( 48name = "crate_index", 49cargo_lockfile = "//:Cargo.lock", 50lockfile = "//:Cargo.Bazel.lock", 51manifests = ["//: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( 69name = "lib", 70aliases = aliases(), 71deps = all_crate_deps( 72normal = True, 73), 74proc_macro_deps = all_crate_deps( 75proc_macro = True, 76), 77) 78 79rust_test( 80name = "unit_test", 81crate = ":lib", 82aliases = aliases( 83normal_dev = True, 84proc_macro_dev = True, 85), 86deps = all_crate_deps( 87normal_dev = True, 88), 89proc_macro_deps = all_crate_deps( 90proc_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( 106name = "crate_index", 107cargo_lockfile = "//:Cargo.lock", 108lockfile = "//:Cargo.Bazel.lock", 109packages = { 110"async-trait": crate.spec( 111version = "0.1.51", 112), 113"mockall": crate.spec( 114version = "0.10.2", 115), 116"tokio": crate.spec( 117version = "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. 123render_config = render_config( 124default_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( 139name = "lib", 140deps = [ 141"@crate_index//:tokio", 142], 143proc_macro_deps = [ 144"@crate_index//:async-trait", 145], 146) 147 148rust_test( 149name = "unit_test", 150crate = ":lib", 151deps = [ 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 165Cargo metadata and compatible with the above approaches; 166 167- Or handwrite your own build target for the binary, use `http_archive` to 168import its source code, and use `crates_repository` to make build targets for 169its dependencies. This is demonstrated below using the `rustfilt` crate as an 170example. 171 172```python 173# in WORKSPACE.bazel 174 175load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") 176 177http_archive( 178name = "rustfilt", 179build_file = "//rustfilt:BUILD.rustfilt.bazel", 180sha256 = "c8d748b182c8f95224336d20dcc5609598af612581ce60cfb29da4dc8d0091f2", 181strip_prefix = "rustfilt-0.2.1", 182type = "tar.gz", 183urls = ["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( 189name = "rustfilt_deps", 190cargo_lockfile = "//rustfilt:Cargo.lock", 191manifests = ["@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( 205name = "rustfilt", 206srcs = glob(["src/**/*.rs"]), 207edition = "2018", 208deps = [ 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( 226name = "crate_index", 227annotations = { 228"thepackage": [crate.annotation( 229gen_binaries = True, 230# Or, to expose just a subset of the package's binaries by name: 231gen_binaries = ["rustfilt"], 232)], 233}, 234# Or, to expose every binary of every package: 235generate_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