This repository provides rules for building Rust projects with Bazel.
The rules are released, and releases can be found on the GitHub Releases page. We recommend using the latest release from that page.
Note that rules_rust bzlmod support is still a work in progress. Most features should work, but bugs are more likely. This is not a desired end-state - please report (or better yet, help fix!) bugs you run into.
To use rules_rust in a project using bzlmod, add the following to your MODULE.bazel file:
bazel_dep(name = "rules_rust", version = "0.46.0")Don't forget to substitute in your desired release's version number.
To use rules_rust in a project using a WORKSPACE file, add the following to your WORKSPACE file to add the external repositories for the Rust toolchain:
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
# To find additional information on this release or newer ones visit:
# https://github.com/bazelbuild/rules_rust/releases
http_archive(
name = "rules_rust",
integrity = "sha256-F8U7+AC5MvMtPKGdLLnorVM84cDXKfDRgwd7/dq3rUY=",
urls = ["https://github.com/bazelbuild/rules_rust/releases/download/0.46.0/rules_rust-v0.46.0.tar.gz"],
)
load("@rules_rust//rust:repositories.bzl", "rules_rust_dependencies", "rust_register_toolchains")
rules_rust_dependencies()
rust_register_toolchains()Don't forget to substitute in your desired release's version number and integrity hash.
- defs: standard rust rules for building and testing libraries and binaries.
- rust_doc: rules for generating and testing rust documentation.
- rust_clippy: rules for running clippy.
- rust_fmt: rules for running rustfmt.
- rust_proto: rules for generating protobuf and gRPC stubs.
- rust_bindgen: rules for generating C++ bindings.
- rust_wasm_bindgen: rules for generating WebAssembly bindings.
- cargo: Rules dedicated to Cargo compatibility. ie:
build.rsscripts. - crate_universe (bzlmod): Rules for generating Bazel targets for external crate dependencies when using bzlmod.
- crate_universe (WORKSPACE): Rules for generating Bazel targets for external crate dependencies when using WORKSPACE files.
You can also browse the full API in one page.
- rust_analyzer: rules for generating
rust-project.jsonfiles for rust-analyzer
To build with a particular version of the Rust compiler, pass that version to rust_register_toolchains:
rust_register_toolchains(
edition = "2021",
versions = [
"1.66.1"
],
)As well as an exact version, versions can accept nightly/{iso_date} and beta/{iso_date} strings for toolchains from different release channels.
rust_register_toolchains(
edition = "2021",
versions = [
"nightly/2022-12-15",
],
)By default, a stable and nightly toolchain will be registered if no versions are passed to rust_register_toolchains. However,
if only 1 version is passed and it is from the nightly or beta release channels (i.e. not stable), then a build setting must
also be set in the project's .bazelrc file.
build --@rules_rust//rust/toolchain/channel=nightly
Failure to do so will result in rules attempting to match a stable toolchain when one was not registered.
crate_universe (crate_universe bzlmod) is a tool built into rules_rust that can be used to fetch dependencies.
The 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.
We 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.
We aim to support Linux and macOS.
We 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.
Windows support for some features requires --enable_runfiles to be passed to Bazel, we recommend putting it in your bazelrc. See Using Bazel on Windows for more Windows-specific recommendations.