fork/rules_rust
git clone https://git.julia.blue/fork/rules_rust
9b61b499
0.10.0
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", 49lockfile = "//:Cargo.Bazel.lock", 50manifests = ["//: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( 68name = "lib", 69aliases = aliases(), 70deps = all_crate_deps( 71normal = True, 72), 73proc_macro_deps = all_crate_deps( 74proc_macro = True, 75), 76) 77 78rust_test( 79name = "unit_test", 80crate = ":lib", 81aliases = aliases( 82normal_dev = True, 83proc_macro_dev = True, 84), 85deps = all_crate_deps( 86normal_dev = True, 87), 88proc_macro_deps = all_crate_deps( 89proc_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( 105name = "crate_index", 106lockfile = "//:Cargo.Bazel.lock", 107packages = { 108"async-trait": crate.spec( 109version = "0.1.51", 110), 111"mockall": crate.spec( 112version = "0.10.2", 113), 114"tokio": crate.spec( 115version = "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. 121render_config = render_config( 122default_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( 137name = "lib", 138deps = [ 139"@crate_index//:tokio", 140], 141proc_macro_deps = [ 142"@crate_index//:async-trait", 143], 144) 145 146rust_test( 147name = "unit_test", 148crate = ":lib", 149deps = [ 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