README.md

cargo-raze

A bazel rule generator for cargo dependencies.

This tool is experimental and no guarantees are made that it will work at all really. It works for the one example in this repo. It was built as a spike to test out possible workflows for a proper tool implementation.

Usage modes

Generate WORKSPACE content

Example invocation (in a Cargo.toml+Cargo.lock bearing directory)

cargo install raze
cargo raze --overrides log-0.3.7:@custom-log//log:log --generate

A generate invocation will yield a series of new_http_archive() invocations into ./raze.WORKSPACE that can be included in the repository's WORKSPACE file to automatically include the selected crates, with generated BUILD rules. An overrides flag is provided to allow users to override references of selected dependencies with their own defined rules. This is a useful feature when the automatically generated build rule fails to compile. Typically, rules that have complex system library dependencies, or leverage build.rs in interesting ways will require a custom override. Overrides in this manner will need to be accessible from your WORKSPACE, meaning they cannot live in the root workspace.

It is not suggested that users manually edit the generated rules, as those edits will have to be persisted when generate is rerun.

Vendoring into ./raze/ or other directory

Example invocation (in a Cargo.toml+Cargo.lock bearing directory)

cargo install raze
cargo raze --overrides log-0.3.7:@custom-log//log:log --vendor ./raze

A vendor invocation will yield the full source code, supplemented with BUILD files into a selected directory. These rules function identically to normal source code. An override feature is provided to prevent vendoring of some dependency, in lieu of a user-customized dependency. This is typically necessary if the dependency leverages build.rs in some novel way.

Supported features

• Build rule generation in vendored source format, or in WORKSPACE format
  • Vendored: acmcarther/raze-manual-example
  • WORKSPACE: acmcarther/raze-autogen-example
• Platform specific dependencies for the environment raze is run on
• Feature flag propagation
• Dependency overriding

Future features

• Platform detection (current platform is hardcoded to generic linux).
• Target platform specification, rather than current system platform
• alias rules for packages directly specified in Cargo.toml
• (potentially) Deferred BUILD file generation, to defer platform specific dependency resolution.
• (potentially) Generating build.rs shim rules, rather than forcing an --override when build_dependencies are present.