Rust rules

rust_library
rust_binary
rust_benchmark
rust_test

rust_benchmark

Builds a Rust benchmark test.

Warning: This rule is currently experimental. Rust Benchmark tests require the Bencher interface in the unstable libtest crate, which is behind the test unstable feature gate. As a result, using this rule would require using a nightly binary release of Rust.

Example:

Suppose you have the following directory structure for a Rust project with a library crate, fibonacci with benchmarks under the benches/ directory:

[workspace]/
  WORKSPACE
  fibonacci/
      BUILD
      src/
          lib.rs
      benches/
          fibonacci_bench.rs

fibonacci/src/lib.rs:

pub fn fibonacci(n: u64) -> u64 {
    if n < 2 {
        return n;
    }
    let mut n1: u64 = 0;
    let mut n2: u64 = 1;
    for _ in 1..n {
        let sum = n1 + n2;
        n1 = n2;
        n2 = sum;
    }
    n2
}

fibonacci/benches/fibonacci_bench.rs:

#![feature(test)]

extern crate test;
extern crate fibonacci;

use test::Bencher;

#[bench]
fn bench_fibonacci(b: &mut Bencher) {
    b.iter(|| fibonacci::fibonacci(40));
}

To build the benchmark test, add a rust_benchmark target:

fibonacci/BUILD:

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

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

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

rust_benchmark(
  name = "fibonacci_bench",
  srcs = ["benches/fibonacci_bench.rs"],
  deps = [":fibonacci"],
)

Run the benchmark test using: bazel run //fibonacci:fibonacci_bench.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
aliases	Remap crates to a new name or moniker for linkage to this target These are other rust_library targets and will be presented as the new name given.	Dictionary: Label -> String	optional	{}
crate_features	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.	List of strings	optional	[]
crate_root	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.	Label	optional	None
data	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.	List of labels	optional	[]
deps	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.	List of labels	optional	[]
edition	The rust edition to use for this crate. Defaults to the edition specified in the rust_toolchain.	String	optional	""
out_dir_tar	Deprecated, do not use, see [#cargo_build_script] instead.	Label	optional	None
proc_macro_deps	List of rust_library targets with kind proc-macro used to help build this library target.	List of labels	optional	[]
rustc_env	Dictionary of additional “key”: “value” environment variables to set for rustc.	Dictionary: String -> String	optional	{}
rustc_flags	List of compiler flags passed to rustc.	List of strings	optional	[]
srcs	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.	List of labels	optional	[]
version	A version to inject in the cargo environment variable.	String	optional	“0.0.0”

rust_binary

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	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
aliases	Remap crates to a new name or moniker for linkage to this target These are other rust_library targets and will be presented as the new name given.	Dictionary: Label -> String	optional	{}
crate_features	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.	List of strings	optional	[]
crate_root	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.	Label	optional	None
crate_type	-	String	optional	“bin”
data	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.	List of labels	optional	[]
deps	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.	List of labels	optional	[]
edition	The rust edition to use for this crate. Defaults to the edition specified in the rust_toolchain.	String	optional	""
linker_script	Link script to forward into linker via rustc options.	Label	optional	None
out_binary	-	Boolean	optional	False
out_dir_tar	Deprecated, do not use, see [#cargo_build_script] instead.	Label	optional	None
proc_macro_deps	List of rust_library targets with kind proc-macro used to help build this library target.	List of labels	optional	[]
rustc_env	Dictionary of additional “key”: “value” environment variables to set for rustc.	Dictionary: String -> String	optional	{}
rustc_flags	List of compiler flags passed to rustc.	List of strings	optional	[]
srcs	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.	List of labels	optional	[]
version	A version to inject in the cargo environment variable.	String	optional	“0.0.0”

rust_library

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	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
aliases	Remap crates to a new name or moniker for linkage to this target These are other rust_library targets and will be presented as the new name given.	Dictionary: Label -> String	optional	{}
crate_features	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.	List of strings	optional	[]
crate_root	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.	Label	optional	None
crate_type	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.	String	optional	“rlib”
data	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.	List of labels	optional	[]
deps	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.	List of labels	optional	[]
edition	The rust edition to use for this crate. Defaults to the edition specified in the rust_toolchain.	String	optional	""
out_dir_tar	Deprecated, do not use, see [#cargo_build_script] instead.	Label	optional	None
proc_macro_deps	List of rust_library targets with kind proc-macro used to help build this library target.	List of labels	optional	[]
rustc_env	Dictionary of additional “key”: “value” environment variables to set for rustc.	Dictionary: String -> String	optional	{}
rustc_flags	List of compiler flags passed to rustc.	List of strings	optional	[]
srcs	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.	List of labels	optional	[]
version	A version to inject in the cargo environment variable.	String	optional	“0.0.0”

rust_test

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.

To run a crate or lib with the #[cfg(test)] configuration, handling inline tests, you should specify the crate directly like so.

rust_test(
    name = "hello_lib_test",
    crate = ":hello_lib",
    # You may add other deps that are specific to the test configuration
    deps = ["//some/dev/dep"],
)

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	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
aliases	Remap crates to a new name or moniker for linkage to this target These are other rust_library targets and will be presented as the new name given.	Dictionary: Label -> String	optional	{}
crate	Target inline tests declared in the given crate These tests are typically those that would be held out under #[cfg(test)] declarations.	Label	optional	None
crate_features	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.	List of strings	optional	[]
crate_root	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.	Label	optional	None
data	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.	List of labels	optional	[]
deps	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.	List of labels	optional	[]
edition	The rust edition to use for this crate. Defaults to the edition specified in the rust_toolchain.	String	optional	""
out_dir_tar	Deprecated, do not use, see [#cargo_build_script] instead.	Label	optional	None
proc_macro_deps	List of rust_library targets with kind proc-macro used to help build this library target.	List of labels	optional	[]
rustc_env	Dictionary of additional “key”: “value” environment variables to set for rustc.	Dictionary: String -> String	optional	{}
rustc_flags	List of compiler flags passed to rustc.	List of strings	optional	[]
srcs	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.	List of labels	optional	[]
version	A version to inject in the cargo environment variable.	String	optional	“0.0.0”

Rust rules

rust_benchmark

rust_binary

rust_library

rust_test

Example: test directory

Example: `test` directory