Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
.bazelci
docs
examples
rust
test
util
.gitignore
AUTHORS
BUILD
CONTRIBUTING.md
CONTRIBUTORS
LICENSE.txt
README.md
WORKSPACE
libc.BUILD

README.md

Build status

Rust Rules

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 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_benchmark(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_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 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.