commit	1678ed042fb45c67a6b65f590f015e12dcb42b53	[log] [tgz]
author	Marco Farrugia <afmarco@gmail.com>	Sat Oct 20 00:36:03 2018 +0000
committer	GitHub <noreply@github.com>	Sat Oct 20 00:36:03 2018 +0000
tree	9b86a19f66c46c8d74225107a627bbb84f6ca5c0
parent	b3c8badf2c10ebad8b71a106d3398e28804728d0 [diff]

tree: 9b86a19f66c46c8d74225107a627bbb84f6ca5c0

README.md

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)

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)

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)

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.

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)

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)

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.

Rust 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

Example: `test` directory