fork/rules_rust
git clone https://git.julia.blue/fork/rules_rust
dec889f0
cleanup
1""" 2# Crate Universe 3 4Crate Universe is a set of Bazel rule for generating Rust targets using Cargo. 5 6This doc describes using crate_universe with bzlmod. 7 8If you're using a WORKSPACE file, please see [the WORKSPACE equivalent of this doc](crate_universe.html). 9 10There are some examples of using crate_universe with bzlmod in the [example folder](../examples/bzlmod). 11 12# Table of Contents 13 141. [Setup](#Setup) 152. [Dependencies](#dependencies) 16* [Cargo Workspace](#cargo-workspaces) 17* [Direct Packages](#direct-dependencies) 18* [Vendored Dependencies](#vendored-dependencies) 193. [Crate reference](#crate) 20* [from_cargo](#from_cargo) 21* [from_specs](#from_specs) 22 23 24## Setup 25 26To use rules_rust in a project using bzlmod, add the following to your MODULE.bazel file: 27 28```starlark 29bazel_dep(name = "rules_rust", version = "0.49.3") 30``` 31 32You find the latest version on the [release page](https://github.com/bazelbuild/rules_rust/releases). 33 34 35After adding `rules_rust` in your MODULE.bazel, set the following to begin using `crate_universe`: 36 37```starlark 38crate = use_extension("@rules_rust//crate_universe:extension.bzl", "crate") 39// # ... Dependencies 40use_repo(crate, "crates") 41``` 42 43## Dependencies 44 45There are three different ways to declare dependencies in your MODULE. 46 471) Cargo workspace 482) Direct Dependencies 493) Vendored Dependencies 50 51### Cargo Workspaces 52 53One of the simpler ways to wire up dependencies would be to first structure your project into a Cargo workspace. 54The crates_repository rule can ingest a root Cargo.toml file and generate Bazel dependencies from there. 55You find a complete example in the in the [example folder](../examples/bzlmod/all_crate_deps). 56 57```starlark 58crate = use_extension("@rules_rust//crate_universe:extension.bzl", "crate") 59 60crate.from_cargo( 61name = "crates", 62cargo_lockfile = "//:Cargo.lock", 63manifests = ["//:Cargo.toml"], 64) 65use_repo(crate, "crates") 66``` 67 68The generated crates_repository contains helper macros which make collecting dependencies for Bazel targets simpler. 69Notably, the all_crate_deps and aliases macros ( 70see [Dependencies API](https://bazelbuild.github.io/rules_rust/crate_universe.html#dependencies-api)) commonly allow the 71Cargo.toml files to be the single source of truth for dependencies. 72Since these macros come from the generated repository, the dependencies and alias definitions 73they return will automatically update BUILD targets. In your BUILD files, 74you use these macros for a Rust library as shown below: 75 76```starlark 77load("@crate_index//:defs.bzl", "aliases", "all_crate_deps") 78load("@rules_rust//rust:defs.bzl", "rust_library", "rust_test") 79 80rust_library( 81name = "lib", 82aliases = aliases(), 83deps = all_crate_deps( 84normal = True, 85), 86proc_macro_deps = all_crate_deps( 87proc_macro = True, 88), 89) 90 91rust_test( 92name = "unit_test", 93crate = ":lib", 94aliases = aliases( 95normal_dev = True, 96proc_macro_dev = True, 97), 98deps = all_crate_deps( 99normal_dev = True, 100), 101proc_macro_deps = all_crate_deps( 102proc_macro_dev = True, 103), 104) 105``` 106 107For a Rust binary that does not depend on any macro, use the following configuration 108in your build file: 109 110```starlark 111rust_binary( 112name = "bin", 113srcs = ["src/main.rs"], 114deps = all_crate_deps(normal = True), 115) 116``` 117 118You have to repin before your first build to ensure all Bazel targets for the macros 119are generated. 120 121Dependency syncing and updating is done in the repository rule which means it's done during the 122analysis phase of builds. As mentioned in the environments variable table above, the `CARGO_BAZEL_REPIN` 123(or `REPIN`) environment variables can be used to force the rule to update dependencies and potentially 124render a new lockfile. Given an instance of this repository rule named `crates`, the easiest way to 125repin dependencies is to run: 126 127```shell 128CARGO_BAZEL_REPIN=1 bazel sync --only=crates 129``` 130 131This will result in all dependencies being updated for a project. The `CARGO_BAZEL_REPIN` 132environment variable can also be used to customize how dependencies are updated. 133For more details about repin, [please refer to the documentation](https://bazelbuild.github.io/rules_rust/crate_universe.html#crates_vendor). 134 135### Direct Dependencies 136 137In cases where Rust targets have heavy interactions with other Bazel targets ([Cc](https://docs.bazel.build/versions/main/be/c-cpp.html), [Proto](https://rules-proto-grpc.com/en/4.5.0/lang/rust.html), 138etc.), maintaining Cargo.toml files may have diminishing returns as things like rust-analyzer 139begin to be confused about missing targets or environment variables defined only in Bazel. 140In situations like this, it may be desirable to have a “Cargo free” setup. You find an example in the in the [example folder](../examples/bzlmod/hello_world_no_cargo). 141 142crates_repository supports this through the packages attribute, 143as shown below. 144 145```starlark 146crate = use_extension("@rules_rust//crate_universe:extension.bzl", "crate") 147 148crate.spec(package = "serde", features = ["derive"], version = "1.0") 149crate.spec(package = "serde_json", version = "1.0") 150crate.spec(package = "tokio", default_features=False, features = ["macros", "net", "rt-multi-thread"], version = "1.38") 151 152crate.from_specs() 153use_repo(crate, "crates") 154``` 155 156Consuming dependencies may be more ergonomic in this case through the aliases defined in the new repository. 157In your BUILD files, you use direct dependencies as shown below: 158 159```starlark 160rust_binary( 161name = "bin", 162crate_root = "src/main.rs", 163srcs = glob([ 164"src/*.rs", 165]), 166deps = [ 167# External crates 168"@crates//:serde", 169"@crates//:serde_json", 170"@crates//:tokio", 171], 172visibility = ["//visibility:public"], 173) 174``` 175 176Notice, direct dependencies do not need repining. 177Only a cargo workspace needs updating whenever the underlying Cargo.toml file changed. 178 179### Vendored Dependencies 180 181In some cases, it is require that all external dependencies are vendored, meaning downloaded 182and stored in the workspace. This helps, for example, to conduct licence scans, apply custom patches, 183or to ensure full build reproducibility since no download error could possibly occur. 184You find a complete example in the in the [example folder](../examples/bzlmod/all_deps_vendor). 185 186For the setup, you need to add the skylib in addition to the rust rules to your MODUE.bazel. 187 188```starlark 189module( 190name = "deps_vendored", 191version = "0.0.0" 192) 193############################################################################### 194# B A Z E L C E N T R A L R E G I S T R Y # https://registry.bazel.build/ 195############################################################################### 196# https://github.com/bazelbuild/bazel-skylib/releases/ 197bazel_dep(name = "bazel_skylib", version = "1.7.1") 198 199# https://github.com/bazelbuild/rules_rust/releases 200bazel_dep(name = "rules_rust", version = "0.49.3") 201 202############################################################################### 203# T O O L C H A I N S 204############################################################################### 205 206# Rust toolchain 207RUST_EDITION = "2021" 208RUST_VERSION = "1.80.1" 209 210rust = use_extension("@rules_rust//rust:extensions.bzl", "rust") 211rust.toolchain( 212edition = RUST_EDITION, 213versions = [RUST_VERSION], 214) 215use_repo(rust, "rust_toolchains") 216register_toolchains("@rust_toolchains//:all") 217 218############################################################################### 219# R U S T C R A T E S 220############################################################################### 221crate = use_extension("@rules_rust//crate_universe:extension.bzl", "crate") 222``` 223 224Note, it is important to load the crate_universe rules otherwise you will get an error 225as the rule set is needed in the vendored target. 226 227Assuming you have a package called `basic` in which you want to vendor dependencies, 228then you create a folder `basic/3rdparty`. The folder name can be arbitrary, 229but by convention, its either thirdparty or 3rdparty to indicate vendored dependencies. 230In the 3rdparty folder, you add a target crates_vendor to declare your dependencies to vendor. 231In the example, we vendor a specific version of bzip2. 232 233```starlark 234load("@rules_rust//crate_universe:defs.bzl", "crate", "crates_vendor") 235 236crates_vendor( 237name = "crates_vendor", 238annotations = { 239"bzip2-sys": [crate.annotation( 240gen_build_script = True, 241)], 242}, 243cargo_lockfile = "Cargo.Bazel.lock", 244generate_build_scripts = False, 245mode = "remote", 246packages = { 247"bzip2": crate.spec( 248version = "=0.3.3", 249), 250}, 251repository_name = "basic", 252tags = ["manual"], 253) 254``` 255 256Next, you have to run `Cargo build` to generate a Cargo.lock file with all resolved dependencies. 257Then, you rename Cargo.lock to Cargo.Bazel.lock and place it inside the `basic/3rdparty` folder. 258 259At this point, you have the following folder and files: 260 261``` 262basic 263├── 3rdparty 264│ ├── BUILD.bazel 265│ ├── Cargo.Bazel.lock 266``` 267 268Now you can run the `crates_vendor` target: 269 270`bazel run //basic/3rdparty:crates_vendor` 271 272This generates a crate folders with all configurations for the vendored dependencies. 273 274``` 275basic 276├── 3rdparty 277│ ├── cratea 278│ ├── BUILD.bazel 279│ ├── Cargo.Bazel.lock 280``` 281 282Suppose you have an application in `basic/src` that is defined in `basic/BUILD.bazel` and 283that depends on a vendored dependency. You find a list of all available vendored dependencies 284in the BUILD file of the generated folder: `basic/3rdparty/crates/BUILD.bazel` 285You declare a vendored dependency in you target as following: 286 287```starlark 288load("@rules_rust//rust:defs.bzl", "rust_binary") 289 290rust_binary( 291name = "hello_sys", 292srcs = ["src/main.rs"], 293deps = ["//basic/3rdparty/crates:bzip2"], 294visibility = ["//visibility:public"], 295) 296``` 297Note, the vendored dependency is not yet accessible because you have to define first 298how to load the vendored dependencies. For that, you first create a file `sys_deps.bzl` 299and add the following content: 300 301```starlark 302# rename the default name "crate_repositories" in case you import multiple vendored folders. 303load("//basic/3rdparty/crates:defs.bzl", basic_crate_repositories = "crate_repositories") 304 305def sys_deps(): 306# Load the vendored dependencies 307basic_crate_repositories() 308``` 309 310This is straightforward, you import the generated crate_repositories from the crates folder, 311rename it to avoid name clashes in case you import from multiple vendored folders, and then 312just load the vendored dependencies. 313 314In a WORKSPACE configuration, you would just load and call sys_deps(), but in a MODULE configuration, you cannot do that. 315Instead, you create a new file `WORKSPACE.bzlmod` and add the following content. 316 317```starlark 318load("//:sys_deps.bzl", "sys_deps") 319sys_deps() 320``` 321 322Now, you can build the project as usual. 323 324There are some more examples of using crate_universe with bzlmod in the [example folder](https://github.com/bazelbuild/rules_rust/blob/main/examples/bzlmod/). 325 326""" 327 328load ( 329"//crate_universe:extension.bzl" , 330_crate = "crate" , 331) 332 333crate = _crate