1# [Rules rust](https://github.com/bazelbuild/rules_rust) 2 3## Overview 4 5This repository provides rules for building [Rust][rust] projects with [Bazel][bazel]. 6 7[bazel]: https://bazel.build/ 8[rust]: http://www.rust-lang.org/ 9 10<!-- TODO: Render generated docs on the github pages site again, https://bazelbuild.github.io/rules_rust/ --> 11 12<a name="setup"></a> 13 14## Setup 15 16To use the Rust rules, add the following to your `WORKSPACE` file to add the external repositories for the Rust toolchain: 17 18```python 19load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") 20 21# To find additional information on this release or newer ones visit: 22# https://github.com/bazelbuild/rules_rust/releases 23http_archive( 24 name = "rules_rust", 25 sha256 = "36ab8f9facae745c9c9c1b33d225623d976e78f2cc3f729b7973d8c20934ab95", 26 urls = ["https://github.com/bazelbuild/rules_rust/releases/download/0.31.0/rules_rust-v0.31.0.tar.gz"], 27) 28 29load("@rules_rust//rust:repositories.bzl", "rules_rust_dependencies", "rust_register_toolchains") 30 31rules_rust_dependencies() 32 33rust_register_toolchains() 34``` 35 36The rules are released, and releases can be found on [the GitHub Releases page](https://github.com/bazelbuild/rules_rust/releases). We recommend using the latest release from that page. 37 38## Rules 39 40- [defs](defs.md): standard rust rules for building and testing libraries and binaries. 41- [rust_doc](rust_doc.md): rules for generating and testing rust documentation. 42- [rust_clippy](rust_clippy.md): rules for running [clippy](https://github.com/rust-lang/rust-clippy#readme). 43- [rust_fmt](rust_fmt.md): rules for running [rustfmt](https://github.com/rust-lang/rustfmt#readme). 44- [rust_proto](rust_proto.md): rules for generating [protobuf](https://developers.google.com/protocol-buffers) and [gRPC](https://grpc.io) stubs. 45- [rust_bindgen](rust_bindgen.md): rules for generating C++ bindings. 46- [rust_wasm_bindgen](rust_wasm_bindgen.md): rules for generating [WebAssembly](https://www.rust-lang.org/what/wasm) bindings. 47- [cargo](cargo.md): Rules dedicated to Cargo compatibility. ie: [`build.rs` scripts](https://doc.rust-lang.org/cargo/reference/build-scripts.html). 48- [crate_universe](crate_universe.md): Rules for generating Bazel targets for external crate dependencies. 49 50You can also browse the [full API in one page](flatten.md). 51 52### Experimental rules 53 54- [rust_analyzer](rust_analyzer.md): rules for generating `rust-project.json` files for [rust-analyzer](https://rust-analyzer.github.io/) 55 56## Specifying Rust version 57 58To build with a particular version of the Rust compiler, pass that version to [`rust_register_toolchains`](flatten.md#rust_register_toolchains): 59 60```python 61rust_register_toolchains( 62 edition = "2021", 63 versions = [ 64 "1.66.1" 65 ], 66) 67``` 68 69As well as an exact version, `versions` can accept `nightly/{iso_date}` and `beta/{iso_date}` strings for toolchains from different release channels. 70 71```python 72rust_register_toolchains( 73 edition = "2021", 74 versions = [ 75 "nightly/2022-12-15", 76 ], 77) 78``` 79 80By default, a `stable` and `nightly` toolchain will be registered if no versions are passed to `rust_register_toolchains`. However, 81if only 1 version is passed and it is from the `nightly` or `beta` release channels (i.e. __not__ `stable`), then a build setting must 82also be set in the project's `.bazelrc` file. 83 84```text 85build --@rules_rust//rust/toolchain/channel=nightly 86``` 87 88Failure to do so will result in rules attempting to match a `stable` toolchain when one was not registered. 89 90## External Dependencies 91 92[crate_universe](crate_universe.md) is a tool built into `rules_rust` that can be used to fetch dependencies. Additionally, [cargo-raze](https://github.com/google/cargo-raze) is an older third-party which can also fetch dependencies. 93 94## Supported bazel versions 95 96The oldest version of Bazel the `main` branch is tested against is `6.3.0`. Previous versions may still be functional in certain environments, but this is the minimum version we strive to fully support. 97 98We test these rules against the latest rolling releases of Bazel, and aim for compatibility with them, but prioritise stable releases over rolling releases where necessary. 99 100## Supported platforms 101 102We aim to support Linux and macOS. 103 104We do not have sufficient maintainer expertise to support Windows. Most things probably work, but we have had to disable many tests in CI because we lack the expertise to fix them. We welcome contributions to help improve its support. 105 106Windows support for some features requires `--enable_runfiles` to be passed to Bazel, we recommend putting it in your bazelrc. See [Using Bazel on Windows](https://bazel.build/configure/windows) for more Windows-specific recommendations. 107