Rust Rules for Bazel

Overview

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

• Setup
• Basic Example
• Build Rule Reference
  • rust_library
  • rust_binary
  • rust_test
• Roadmap

Setup

To use the Rust rules, simply copy the contents of rust.WORKSPACE to your WORKSPACE file.

Basic 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("/tools/build_rules/rust/rust", "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

Now, let's add a binary crate that uses the hello_lib library. The directory structure now looks like the following:

[workspace]/
    WORKSPACE
    hello_lib/
        BUILD
        src/
            greeter.rs
            lib.rs
    hello_world/
        BUILD
        src/
            main.rs

hello_world/src/main.rs:

extern crate hello_lib;

use hello_lib::greeter;

fn main() {
    let hello = greeter::Greeter::new("Hello");
    hello.greet("world");
}

hello_world/BUILD:

load("/tools/build_rules/rust/rust", "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

Build Rule Reference

rust_library

rust_library(name, srcs, deps, data, crate_features, rustc_flags)

rust_binary

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

rust_test

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

Roadmap

Near-term roadmap

• Implement rust_bench_test rule for running benchmarks.
• Enable rust_test to depend solely on a rust_library since many projects intermix #[test] methods in implementation source.
• Improve documentation with more detailed examples.
• Implement rust_doc rule for generating rustdoc documentation.

Longer-term 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.