A Gazelle language plugin for Rust; automatic dependency management for Rust projects built with Bazel.
References:
example/WORKSPACE
shows how
to load rules_rust and gazelle_rust together. In a real project, you would need to use
http_archive
instead of local_repository
, for example:
GAZELLE_RUST_COMMIT = "<commit>"
GAZELLE_RUST_SHA256 = "<hash>"
http_archive(
name = "gazelle_rust",
sha256 = GAZELLE_RUST_SHA256,
strip_prefix = "gazelle_rust-{}".format(GAZELLE_RUST_COMMIT),
url = "https://github.com/Calsign/gazelle_rust/archive/{}.zip".format(GAZELLE_RUST_COMMIT),
)
gazelle_rust doesn't have any releases yet, so please just pick the latest commit on main
. To
determine the sha256, first set the value to None
, then fill in the sha256 that bazel tells you.
gazelle_rust requires rules_rust 0.40.0 or later. Previous versions required a patch to rules_rust.
The dependencies for gazelle_rust itself are loaded through two repository rule macros, shown in
example/WORKSPACE
. This includes setting up gazelle, but you may use a different gazelle version
by loading the gazelle repo before calling gazelle_rust_dependencies*
.
gazelle_rust includes a patch to gazelle which allows for reporting unused crate_universe dependencies. If you do not include the patch, everything else will still work fine but unused crate_universe dependencies will not be reported.
example/BUILD.bazel
shows
how to create the gazelle target. With the gazelle target defined, you can run it:
bazel run //:gazelle
This will modify your build files in-place to create and update rust targets for all of the rust files in your project.
gazelle_rust provides a premade gazelle binary, but you can also create your own gazelle_binary
target and add @gazelle_rust//rust_language
to languages.
example/src/BUILD.bazel
shows sample targets generated by gazelle. The following rules are supported:
rust_library
rust_binary
rust_test
rust_proc_macro
rust_shared_library
rust_static_library
When generating targets for new sources (those not already listed in srcs
for an existing target),
gazelle_rust will infer the rule kind based on information like whether the file has a main
and
the name of the directory. The full logic is in inferRuleKind
in
rust_language/generate.go
.
If you change the rule kind afterward, gazelle_rust will respect the existing rule kind.
By default gazelle_rust will generate one target per source file. You may change the grouping by
adding a file to srcs
for an existing target, and gazelle will respect that existing grouping.
gazelle_rust does not currently support sources in subdirectories, and will always place targets into build files adjacent to the sources that they correspond to.
gazelle_rust parses each source file and identifies any path that looks like an external crate
dependency. For example some_lib::Foobar
implies a new dependency on some_lib
unless some_lib
is already in scope.
This approach is fairly robust. Please see
rust_parser/parser.rs
for implementation details and the parser
tests for the range of
cases covered. The only known case that is not handled is paths in macros like println!
, which is
quite tricky. (Derive macros are handled properly.)
For each dependency, gazelle_rust identifies the crate in the project (or crate universe dependency) providing that crate name. gazelle_rust raises an error if the crate could not be found or more than one crate with that name was found.
This means there is a global namespace of crates within the project. If this poses an issue for you,
you can use the gazelle resolve
directive to configure which target is
selected on a per-directory basis.
The example shows how to handle crate universe dependencies with gazelle_rust.
example/WORKSPACE
shows how
to load crate universe dependencies, please refer to the rules_rust
documentation for more information. The
example shows the repository rule approach, but gazelle_rust also supports the vendored approach.
example/BUILD.bazel
shows
how to configure gazelle_rust to resolve crate universe dependencies.
Different configurations of crate universe use either a cargo lockfile (Cargo.lock
) or a custom
lockfile (Cargo.Bazel.lock
), and gazelle_rust supports both. Use the directive
gazelle:rust_cargo_lockfile
to indicate a cargo lockfile and gazelle:rust_lockfile
to indicate a
custom lockfile. These options are mutually exclusive.
Additionally, you must tell rules_rust the prefix for all crate universe labels using the
gazelle:rust_crates_prefix
directive, e.g. @crates//:
for a repository rule approach or
//3rdparty/crates:
for a vendored approach.
Some situations are too complex for gazelle_rust to handle, such as platform-conditional
dependencies. It is possible that fancy support could be added in the future, but for now you must
handle this manually by ignoring the dependency in the source file and potentially adding # keep
comments in the build file.
To tell gazelle_rust to ignore a dependency, you can add the #[gazelle::ignore]
attribute macro
to a use item. For example:
// the tokio runtime is not supported in wasm
#[cfg(not(target_arch = "wasm32"))]
#[gazelle::ignore]
use tokio::runtime::Runtime;
Then in the build file:
rust_library(
name = "maybe_tokio",
deps = select({
"@platforms//cpu:wasm32": [],
"//conditions:default": [
"//3rdparty/crates:tokio",
],
}),
)
rust_library(
name = "some_cool_cross_platform_thing",
deps = [
":maybe_tokio", # keep
],
...
)
See the macro crate for more information about the ignore macro.