rust_binary

rust_binary(name, crate_features, crate_root, data, deps, edition, out_dir_tar, rustc_flags, srcs, version)

Builds a Rust binary crate.

Example:

Suppose you have the following directory structure for a Rust project with a library crate, hello_lib, and a binary crate, hello_world that uses the hello_lib library:

[workspace]/
    WORKSPACE
    hello_lib/
        BUILD
        src/
            lib.rs
    hello_world/
        BUILD
        src/
            main.rs

hello_lib/src/lib.rs:

pub struct Greeter {
    greeting: String,
}

impl Greeter {
    pub fn new(greeting: &str) -> Greeter {
        Greeter { greeting: greeting.to_string(), }
    }

    pub fn greet(&self, thing: &str) {
        println!("{} {}", &self.greeting, thing);
    }
}

hello_lib/BUILD:

package(default_visibility = ["//visibility:public"])

load("@io_bazel_rules_rust//rust:rust.bzl", "rust_library")

rust_library(
    name = "hello_lib",
    srcs = ["src/lib.rs"],
)

hello_world/src/main.rs:

extern crate hello_lib;

fn main() {
    let hello = hello_lib::Greeter::new("Hello");
    hello.greet("world");
}

hello_world/BUILD:

load("@io_bazel_rules_rust//rust:rust.bzl", "rust_binary")

rust_binary(
    name = "hello_world",
    srcs = ["src/main.rs"],
    deps = ["//hello_lib"],
)

Build and run hello_world:

$ bazel run //hello_world
INFO: Found 1 target...
Target //examples/rust/hello_world:hello_world up-to-date:
  bazel-bin/examples/rust/hello_world/hello_world
INFO: Elapsed time: 1.308s, Critical Path: 1.22s

INFO: Running command line: bazel-bin/examples/rust/hello_world/hello_world
Hello world

Attributes

`name`	Name; required A unique name for this target.
`crate_features`	List of strings; optional List of features to enable for this crate. Features are defined in the code using the `#[cfg(feature = "foo")]` configuration option. The features listed here will be passed to `rustc` with `--cfg feature="${feature_name}"` flags.
`crate_root`	Label; optional The file that will be passed to `rustc` to be used for building this crate. If `crate_root` is not set, then this rule will look for a `lib.rs` file (or `main.rs` for rust_binary) or the single file in `srcs` if `srcs` contains only one file.
`data`	List of labels; optional List of files used by this rule at runtime. This attribute can be used to specify any data files that are embedded into the library, such as via the `include_str!` macro.
`deps`	List of labels; optional List of other libraries to be linked to this library target. These can be either other `rust_library` targets or `cc_library` targets if linking a native library.
`edition`	String; optional The rust edition to use for this crate. Defaults to the edition specified in the rust_toolchain.
`out_dir_tar`	Label; optional An optional tar or tar.gz file unpacked and passed as OUT_DIR. Many library crates in the Rust ecosystem require sources to be provided to them in the form of an OUT_DIR argument. This argument can be used to supply the contents of this directory.
`rustc_flags`	List of strings; optional List of compiler flags passed to `rustc`.
`srcs`	List of labels; optional List of Rust `.rs` source files used to build the library. If `srcs` contains more than one file, then there must be a file either named `lib.rs`. Otherwise, `crate_root` must be set to the source file that is the root of the crate to be passed to rustc to build this crate.
`version`	String; optional A version to inject in the cargo environment variable.

rust_doc

rust_doc(name, dep, html_after_content, html_before_content, html_in_header, markdown_css)

Attributes

`name`	Name; required A unique name for this target.
`dep`	Label; required The crate to generate documentation for.
`html_after_content`	Label; optional
`html_before_content`	Label; optional
`html_in_header`	Label; optional
`markdown_css`	List of labels; optional

rust_doc_test

rust_doc_test(name, dep)

Runs Rust documentation tests.

Example:

Suppose you have the following directory structure for a Rust library crate:

[workspace]/
  WORKSPACE
  hello_lib/
      BUILD
      src/
          lib.rs

To run documentation tests for the hello_lib crate, define a rust_doc_test target that depends on the hello_lib rust_library target:

package(default_visibility = ["//visibility:public"])

load("@io_bazel_rules_rust//rust:rust.bzl", "rust_library", "rust_doc_test")

rust_library(
    name = "hello_lib",
    srcs = ["src/lib.rs"],
)

rust_doc_test(
    name = "hello_lib_doc_test",
    dep = ":hello_lib",
)

Running bazel test //hello_lib:hello_lib_doc_test will run all documentation tests for the hello_lib library crate.

Attributes

name

Name; required

A unique name for this target.

dep

Label; required

The label of the target to run documentation tests for.

rust_doc_test can run documentation tests for the source files of rust_library or rust_binary targets.

rust_grpc_library

rust_grpc_library(name, deps, rust_deps)

Builds a Rust library crate from a set of proto_librarys suitable for gRPC.

Example:

load("@io_bazel_rules_rust//proto:proto.bzl", "rust_grpc_library")
load("@io_bazel_rules_rust//proto:toolchain.bzl", "GRPC_COMPILE_DEPS")

proto_library(
    name = "my_proto",
    srcs = ["my.proto"]
)

rust_grpc_library(
    name = "rust",
    deps = [":my_proto"],
)

rust_binary(
    name = "my_service",
    srcs = ["my_service.rs"],
    deps = [":rust"] + GRPC_COMPILE_DEPS,
)

Attributes

`name`	Name; required A unique name for this target.
`deps`	List of labels; required List of proto_library dependencies that will be built. One crate for each proto_library will be created with the corresponding gRPC stubs.
`rust_deps`	List of labels; optional The crates the generated library depends on.

rust_library

rust_library(name, crate_features, crate_root, crate_type, data, deps, edition, out_dir_tar, rustc_flags, srcs, version)

Builds a Rust library crate.

Example:

Suppose you have the following directory structure for a simple Rust library crate:

[workspace]/
    WORKSPACE
    hello_lib/
        BUILD
        src/
            greeter.rs
            lib.rs

hello_lib/src/greeter.rs:

pub struct Greeter {
    greeting: String,
}

impl Greeter {
    pub fn new(greeting: &str) -> Greeter {
        Greeter { greeting: greeting.to_string(), }
    }

    pub fn greet(&self, thing: &str) {
        println!("{} {}", &self.greeting, thing);
    }
}

hello_lib/src/lib.rs:

pub mod greeter;

hello_lib/BUILD:

package(default_visibility = ["//visibility:public"])

load("@io_bazel_rules_rust//rust:rust.bzl", "rust_library")

rust_library(
    name = "hello_lib",
    srcs = [
        "src/greeter.rs",
        "src/lib.rs",
    ],
)

Build the library:

$ bazel build //hello_lib
INFO: Found 1 target...
Target //examples/rust/hello_lib:hello_lib up-to-date:
  bazel-bin/examples/rust/hello_lib/libhello_lib.rlib
INFO: Elapsed time: 1.245s, Critical Path: 1.01s

Attributes

`name`	Name; required A unique name for this target.
`crate_features`	List of strings; optional List of features to enable for this crate. Features are defined in the code using the `#[cfg(feature = "foo")]` configuration option. The features listed here will be passed to `rustc` with `--cfg feature="${feature_name}"` flags.
`crate_root`	Label; optional The file that will be passed to `rustc` to be used for building this crate. If `crate_root` is not set, then this rule will look for a `lib.rs` file (or `main.rs` for rust_binary) or the single file in `srcs` if `srcs` contains only one file.
`crate_type`	String; optional The type of linkage to use for building this library. Options include "lib", "rlib", "dylib", "cdylib", "staticlib", and "proc-macro". The exact output file will depend on the toolchain used.
`data`	List of labels; optional List of files used by this rule at runtime. This attribute can be used to specify any data files that are embedded into the library, such as via the `include_str!` macro.
`deps`	List of labels; optional List of other libraries to be linked to this library target. These can be either other `rust_library` targets or `cc_library` targets if linking a native library.
`edition`	String; optional The rust edition to use for this crate. Defaults to the edition specified in the rust_toolchain.
`out_dir_tar`	Label; optional An optional tar or tar.gz file unpacked and passed as OUT_DIR. Many library crates in the Rust ecosystem require sources to be provided to them in the form of an OUT_DIR argument. This argument can be used to supply the contents of this directory.
`rustc_flags`	List of strings; optional List of compiler flags passed to `rustc`.
`srcs`	List of labels; optional List of Rust `.rs` source files used to build the library. If `srcs` contains more than one file, then there must be a file either named `lib.rs`. Otherwise, `crate_root` must be set to the source file that is the root of the crate to be passed to rustc to build this crate.
`version`	String; optional A version to inject in the cargo environment variable.

rust_proto_library

rust_proto_library(name, deps, rust_deps)

Builds a Rust library crate from a set of proto_librarys.

Example:

load("@io_bazel_rules_rust//proto:proto.bzl", "rust_proto_library")
load("@io_bazel_rules_rust//proto:toolchain.bzl", "PROTO_COMPILE_DEPS")

proto_library(
    name = "my_proto",
    srcs = ["my.proto"]
)

proto_rust_library(
    name = "rust",
    deps = [":my_proto"],
)

rust_binary(
    name = "my_proto_binary",
    srcs = ["my_proto_binary.rs"],
    deps = [":rust"] + PROTO_COMPILE_DEPS,
)

Attributes

`name`	Name; required A unique name for this target.
`deps`	List of labels; required List of proto_library dependencies that will be built. One crate for each proto_library will be created with the corresponding stubs.
`rust_deps`	List of labels; optional The crates the generated library depends on.

rust_proto_toolchain

rust_proto_toolchain(name, edition, grpc_compile_deps, grpc_plugin, proto_compile_deps, proto_plugin, protoc)

Declares a Rust Proto toolchain for use.

This is used to configure proto compilation and can be used to set different protobuf compiler plugin.

Example:

Suppose a new nicer gRPC plugin has came out. The new plugin can be used in Bazel by defining a new toolchain definition and declaration:

load('@io_bazel_rules_rust//proto:toolchain.bzl', 'rust_proto_toolchain')

rust_proto_toolchain(
   name="rust_proto_impl",
   grpc_plugin="@rust_grpc//:grpc_plugin",
   grpc_compile_deps=["@rust_grpc//:grpc_deps"],
)

toolchain(
    name="rust_proto",
    exec_compatible_with = [
        "@platforms//cpu:cpuX",
    ],
    target_compatible_with = [
        "@platforms//cpu:cpuX",
    ],
    toolchain = ":rust_proto_impl",
)

Then, either add the label of the toolchain rule to register_toolchains in the WORKSPACE, or pass it to the "--extra_toolchains" flag for Bazel, and it will be used.

See @io_bazel_rules_rust//proto:BUILD for examples of defining the toolchain.

Attributes

`name`	Name; required A unique name for this target.
`edition`	String; optional The edition used by the generated rust source.
`grpc_compile_deps`	List of labels; optional The compile-time dependencies for the generated gRPC stubs.
`grpc_plugin`	Label; optional The location of the Rust protobuf compiler pugin to generate rust gRPC stubs.
`proto_compile_deps`	List of labels; optional The compile-time dependencies for the generated protobuf stubs.
`proto_plugin`	Label; optional The location of the Rust protobuf compiler plugin used to generate rust sources.
`protoc`	Label; optional The location of the `protoc` binary. It should be an executable target.

rust_test

rust_test(name, crate_features, crate_root, data, deps, edition, out_dir_tar, rustc_flags, srcs, version)

Builds a Rust test crate.

Examples:

Suppose you have the following directory structure for a Rust library crate with unit test code in the library sources:

[workspace]/
    WORKSPACE
    hello_lib/
        BUILD
        src/
            lib.rs

hello_lib/src/lib.rs:

pub struct Greeter {
    greeting: String,
}

impl Greeter {
    pub fn new(greeting: &str) -> Greeter {
        Greeter { greeting: greeting.to_string(), }
    }

    pub fn greet(&self, thing: &str) {
        println!("{} {}", &self.greeting, thing);
    }
}

#[cfg(test)]
mod test {
    use super::Greeter;

    #[test]
    fn test_greeting() {
        let hello = Greeter::new("Hi");
        assert_eq!("Hi Rust", hello.greeting("Rust"));
    }
}

To build and run the tests, simply add a rust_test rule with no srcs and only depends on the hello_lib rust_library target:

hello_lib/BUILD:

package(default_visibility = ["//visibility:public"])

load("@io_bazel_rules_rust//rust:rust.bzl", "rust_library", "rust_test")

rust_library(
    name = "hello_lib",
    srcs = ["src/lib.rs"],
)

rust_test(
    name = "hello_lib_test",
    deps = [":hello_lib"],
)

Run the test with bazel build //hello_lib:hello_lib_test.

Example: `test` directory

Integration tests that live in the tests directory, they are essentially built as separate crates. Suppose you have the following directory structure where greeting.rs is an integration test for the hello_lib library crate:

[workspace]/
    WORKSPACE
    hello_lib/
        BUILD
        src/
            lib.rs
        tests/
            greeting.rs

hello_lib/tests/greeting.rs:

extern crate hello_lib;

use hello_lib;

#[test]
fn test_greeting() {
    let hello = greeter::Greeter::new("Hello");
    assert_eq!("Hello world", hello.greeting("world"));
}

To build the greeting.rs integration test, simply add a rust_test target with greeting.rs in srcs and a dependency on the hello_lib target:

hello_lib/BUILD:

package(default_visibility = ["//visibility:public"])

load("@io_bazel_rules_rust//rust:rust.bzl", "rust_library", "rust_test")

rust_library(
    name = "hello_lib",
    srcs = ["src/lib.rs"],
)

rust_test(
    name = "greeting_test",
    srcs = ["tests/greeting.rs"],
    deps = [":hello_lib"],
)

Run the test with bazel build //hello_lib:hello_lib_test.

Attributes

`name`	Name; required A unique name for this target.
`crate_features`	List of strings; optional List of features to enable for this crate. Features are defined in the code using the `#[cfg(feature = "foo")]` configuration option. The features listed here will be passed to `rustc` with `--cfg feature="${feature_name}"` flags.
`crate_root`	Label; optional The file that will be passed to `rustc` to be used for building this crate. If `crate_root` is not set, then this rule will look for a `lib.rs` file (or `main.rs` for rust_binary) or the single file in `srcs` if `srcs` contains only one file.
`data`	List of labels; optional List of files used by this rule at runtime. This attribute can be used to specify any data files that are embedded into the library, such as via the `include_str!` macro.
`deps`	List of labels; optional List of other libraries to be linked to this library target. These can be either other `rust_library` targets or `cc_library` targets if linking a native library.
`edition`	String; optional The rust edition to use for this crate. Defaults to the edition specified in the rust_toolchain.
`out_dir_tar`	Label; optional An optional tar or tar.gz file unpacked and passed as OUT_DIR. Many library crates in the Rust ecosystem require sources to be provided to them in the form of an OUT_DIR argument. This argument can be used to supply the contents of this directory.
`rustc_flags`	List of strings; optional List of compiler flags passed to `rustc`.
`srcs`	List of labels; optional List of Rust `.rs` source files used to build the library. If `srcs` contains more than one file, then there must be a file either named `lib.rs`. Otherwise, `crate_root` must be set to the source file that is the root of the crate to be passed to rustc to build this crate.
`version`	String; optional A version to inject in the cargo environment variable.

rust_toolchain

rust_toolchain(name, debug_info, default_edition, dylib_ext, exec_triple, opt_level, os, rust_doc, rust_lib, rustc, rustc_lib, staticlib_ext, target_triple)

Declares a Rust toolchain for use.

This is for declaring a custom toolchain, eg. for configuring a particular version of rust or supporting a new platform.

Example:

Suppose the core rust team has ported the compiler to a new target CPU, called cpuX. This support can be used in Bazel by defining a new toolchain definition and declaration:

load('@io_bazel_rules_rust//rust:toolchain.bzl', 'rust_toolchain')

rust_toolchain(
  name = "rust_cpuX_impl",
  rustc = "@rust_cpuX//:rustc",
  rustc_lib = "@rust_cpuX//:rustc_lib",
  rust_lib = "@rust_cpuX//:rust_lib",
  rust_doc = "@rust_cpuX//:rustdoc",
  staticlib_ext = ".a",
  dylib_ext = ".so",
  os = "linux",
)

toolchain(
  name = "rust_cpuX",
  exec_compatible_with = [
    "@platforms//cpu:cpuX",
  ],
  target_compatible_with = [
    "@platforms//cpu:cpuX",
  ],
  toolchain = ":rust_cpuX_impl",
)

Then, either add the label of the toolchain rule to register_toolchains in the WORKSPACE, or pass it to the "--extra_toolchains" flag for Bazel, and it will be used.

See @io_bazel_rules_rust//rust:repositories.bzl for examples of defining the @rust_cpuX repository with the actual binaries and libraries.

Attributes

`name`	Name; required A unique name for this target.
`debug_info`	Dictionary: String -> String; optional
`default_edition`	String; optional The edition to use for rust_* rules that don't specify an edition.
`dylib_ext`	String; required
`exec_triple`	String; optional
`opt_level`	Dictionary: String -> String; optional
`os`	String; required
`rust_doc`	Label; optional The location of the `rustdoc` binary. Can be a direct source or a filegroup containing one item.
`rust_lib`	Label; optional The rust standard library.
`rustc`	Label; optional The location of the `rustc` binary. Can be a direct source or a filegroup containing one item.
`rustc_lib`	Label; optional The libraries used by rustc during compilation.
`staticlib_ext`	String; required
`target_triple`	String; optional

rust_bindgen_toolchain

rust_bindgen_toolchain(name, bindgen, clang, libclang, libstdcxx, rustfmt)

The tools required for the rust_bindgen rule.

Attributes

`name`	Name; required A unique name for this target.
`bindgen`	Label; optional The label of a `bindgen` executable.
`clang`	Label; optional The label of a `clang` executable.
`libclang`	Label; optional A cc_library that provides bindgen's runtime dependency on libclang.
`libstdcxx`	Label; optional A cc_library that satisfies libclang's libstdc++ dependency.
`rustfmt`	Label; optional The label of a `rustfmt` executable. If this is provided, generated sources will be formatted.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

index.md

index.md

rust_binary

Attributes

rust_doc

Attributes

rust_doc_test

Attributes

rust_grpc_library

Attributes

rust_library

Attributes

rust_proto_library

Attributes

rust_proto_toolchain

Attributes

rust_test

Example: `test` directory

Attributes

rust_toolchain

Attributes

rust_bindgen_toolchain

Attributes

Files

index.md

Latest commit

History

index.md

File metadata and controls

rust_binary

Attributes

rust_doc

Attributes

rust_doc_test

Attributes

rust_grpc_library

Attributes

rust_library

Attributes

rust_proto_library

Attributes

rust_proto_toolchain

Attributes

rust_test

Example: test directory

Attributes

rust_toolchain

Attributes

rust_bindgen_toolchain

Attributes

Example: `test` directory