Rust Rules

Rules

• rust_library
• rust_binary
• rust_test
• rust_bench_test
• rust_doc
• rust_doc_test

Overview

These build rules are used for building Rust projects with Bazel.

Setup

To use the Rust rules, add the following to your WORKSPACE file to add the external repositories for the Rust toolchain:

Bazel <= 0.6.1

http_archive(
    name = "io_bazel_rules_rust",
    sha256 = "615639cfd5459fec4b8a5751112be808ab25ba647c4c1953d29bb554ef865da7",
    strip_prefix = "rules_rust-0.0.6",
    urls = [
        "http://bazel-mirror.storage.googleapis.com/github.com/bazelbuild/rules_rust/archive/0.0.6.tar.gz",
        "https://github.com/bazelbuild/rules_rust/archive/0.0.6.tar.gz",
    ],
)

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

rust_repositories()

Bazel Latest

The master branch should always be current with the latest bazel, as such you can pin to a recent commit on master.

Roadmap

• Add rust_toolchain rule to make it easy to use a custom Rust toolchain.
• Add tool for taking Cargo.toml and generating a WORKSPACE file with workspace rules for pulling external dependencies.
• Improve expressiveness of features and support for Cargo's feature groups.
• Add cargo_crate workspace rule for pulling crates from Cargo.

rust_library

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

Attributes
name	Name, required A unique name for this rule. This name will also be used as the name of the library crate built by this rule.
srcs	List of labels, required 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.
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 the single file in srcs if srcs contains only one file.
crate_type	String, optional The type of crate to be produced during library compilation. This list closely matches Cargo's own notion of crate-type, and the available options are "lib", "rlib", "dylib", "cdylib", "staticlib", and "proc-macro". The exact output depends on the selected toolchain but generally will match what Cargo would do. If binary compilation is desired, use rust_binary instead of the "bin" crate type.
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.
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.
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.
rustc_flags	List of strings, optional List of compiler flags passed to rustc.
version	String, optional Version to inject in the cargo environment variable.
out_dir_tar	A single compressed tar or tar.gz file A prepared .tar.gz file to be unpacked and supplied to rustc as an "OUT_DIR" environment variable. Commonly used by Rust sources for outputs of code generation. Crates accept only a single out dir tar to retain parity with Cargo.

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

rust_binary

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

Attributes
name	Name, required A unique name for this rule. This name will also be used as the name of the binary crate built by this rule.
srcs	List of labels, required List of Rust .rs source files used to build the binary. If srcs contains more than one file, then there must be a file either named main.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.
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 main.rs file or the single file in srcs if srcs contains only one file.
deps	List of labels, optional List of other libraries to be linked to this library target. These must be rust_library targets.
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.
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.
rustc_flags	List of strings, optional List of compiler flags passed to rustc.
version	String, optional Version to inject in the cargo environment variable.
out_dir_tar	A single compressed tar or tar.gz file A prepared .tar.gz file to be unpacked and supplied to rustc as an "OUT_DIR" environment variable. Commonly used by Rust sources for outputs of code generation. Crates accept only a single out dir tar to retain parity with Cargo.

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

rust_test

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

Attributes
name	Name, required A unique name for this rule. This name will also be used as the name of the binary test crate built by this rule.
srcs	List of labels, required 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.
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 the single file in srcs if srcs contains only one file.
deps	List of labels, optional List of other libraries to be linked to this test target. These must be rust_library targets.
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.
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.
rustc_flags	List of strings, optional List of compiler flags passed to rustc.
version	String, optional Version to inject in the cargo environment variable.
out_dir_tar	A single compressed tar or tar.gz file A prepared .tar.gz file to be unpacked and supplied to rustc as an "OUT_DIR" environment variable. Commonly used by Rust sources for outputs of code generation. Crates accept only a single out dir tar to retain parity with Cargo.

Example

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 greeting(&self, thing: &str) -> String {
        return format!("{} {}", &self.greeting, thing);
    }

    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.

rust_bench_test

rust_bench_test(name, srcs, deps, data, crate_features, rustc_flags, out_dir_tar)

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. A rust_toolchain rule will be added in the near future to make it easy to use a custom Rust toolchain, such as a nightly release.

Attributes
name	Name, required A unique name for this rule. This name will also be used as the name of the binary test crate built by this rule.
srcs	List of labels, required 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.
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 the single file in srcs if srcs contains only one file.
deps	List of labels, optional List of other libraries to be linked to this test target. These must be rust_library targets.
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.
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.
rustc_flags	List of strings, optional List of compiler flags passed to rustc.
out_dir_tar	A single compressed tar or tar.gz file A prepared .tar.gz file to be unpacked and supplied to rustc as an "OUT_DIR" environment variable. Commonly used by Rust sources for outputs of code generation. Crates accept only a single out dir tar to retain parity with Cargo.

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, simply add a rust_bench_test target:

fibonacci/BUILD:

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

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

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

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

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

rust_doc

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

Attribute	Description
name	Name, required A unique name for this rule.
dep	Label, required The label of the target to generate code documentation for. rust_doc can generate HTML code documentation for the source files of rust_library or rust_binary targets.
markdown_css	List of Labels, optional CSS files to include via <link> in a rendered Markdown file.
html_in_header	Label, optional File to add to <head>.
html_before_content	Label, optional File to add in <body>, before content.
html_after_content	Label, optional File to add in <body>, after content.

Example

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

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

To build rustdoc documentation for the hello_lib crate, define a rust_doc rule that depends on the the hello_lib rust_library target:

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

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

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

rust_doc(
    name = "hello_lib_doc",
    dep = ":hello_lib",
)

Running bazel build //hello_lib:hello_lib_doc will build a zip file containing the documentation for the hello_lib library crate generated by rustdoc.

rust_doc_test

rust_doc_test(name, dep)

Attribute	Description
name	Name, required A unique name for this rule.
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.

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.