fork/rules_rust
git clone https://git.julia.blue/fork/rules_rust
42f78f25
0.8.1
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( 52name = "crate_index", 53lockfile = "//:Cargo.Bazel.lock", 54manifests = ["//: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( 72name = "lib", 73aliases = aliases(), 74deps = all_crate_deps( 75normal = True, 76), 77proc_macro_deps = all_crate_deps( 78proc_macro = True, 79), 80) 81 82rust_test( 83name = "unit_test", 84crate = ":lib", 85aliases = aliases( 86normal_dev = True, 87proc_macro_dev = True, 88), 89deps = all_crate_deps( 90normal_dev = True, 91), 92proc_macro_deps = all_crate_deps( 93proc_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( 109name = "crate_index", 110lockfile = "//:Cargo.Bazel.lock", 111packages = { 112"async-trait": crate.spec( 113version = "0.1.51", 114), 115"mockall": crate.spec( 116version = "0.10.2", 117), 118"tokio": crate.spec( 119version = "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. 125render_config = render_config( 126default_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( 141name = "lib", 142deps = [ 143"@crate_index//:tokio", 144], 145proc_macro_deps = [ 146"@crate_index//:async-trait", 147], 148) 149 150rust_test( 151name = "unit_test", 152crate = ":lib", 153deps = [ 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