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.

Name		Name	Last commit message	Last commit date
Latest commit History 85 Commits
.bazelci		.bazelci
docs		docs
examples		examples
rust		rust
test		test
.gitignore		.gitignore
AUTHORS		AUTHORS
CONTRIBUTING.md		CONTRIBUTING.md
CONTRIBUTORS		CONTRIBUTORS
LICENSE.txt		LICENSE.txt
README.md		README.md
WORKSPACE		WORKSPACE
libc.BUILD		libc.BUILD

License

vitalyd/rules_rust

Folders and files

Latest commit

History

Repository files navigation

Rust Rules

Rules

Overview

Setup

Bazel <= 0.6.1

Bazel Latest

Roadmap

rust_library

Example

rust_binary

Example

rust_test

Example

Example: test directory

rust_bench_test

Example

rust_doc

Example

rust_doc_test

Example

About

Resources

License

Stars

Watchers

Forks

Languages

Example: `test` directory