2.6 KiB
Rules Rust - Architecture
In this file we describe how we think about the architecture
of rules_rust. Its goal is to help contributors orient themselves, and to
document code restrictions and assumptions.
In general we try to follow the common standard defined by https://docs.bazel.build/versions/master/skylark/deploying.html.
//rust
This is the core package of the rules. It contains all the core rules such as
rust_binary and rust_library. It also contains rust_common, a Starlark
struct providing all rules_rust APIs that one might need when writing custom
rules integrating with rules_rust.
//rust and all its subpackages have to be standalone. Users who only need
the core rules should be able to ignore all other packages.
//rust:defs.bzl is the file that all users of rules_rust will be using.
Everything in this file can be used (depended on) and is supported (though
stability is not currently guaranteed across commits, see
#600). Typically this
file re-exports definitions from other files, typically from //rust/private.
Also other packages in rules_rust should access core rules through the public
API only. We expect dogfooding our own APIs increases their
quality.
//rust/private package contains code for rule implementation. This file can only
depend on //rust and its subpackages. Exceptions are Bazel's builtin packages
and public APIs of other rules (such as rules_cc). Depending on
//rust/private from packages other than //rust is not supported, we reserve
the right to change anything there and not tell anybody.
When core rules need custom tools (such as process wrapper, launcher, test
runner, and so on), they should be stored in //rust/tools (for public tools)
or in //rust/private/tools (for private tools). These should:
- be essential (it does not make sense to have core rules without them)
- have few or no third party dependencies, and their third party dependencies should be checked in.
- be usable for cross compilation
- have only essential requirements on the host system (requiring that a custom library is installed on the system is frowned upon)
//examples (@examples)
Examples package is actually a local repository. This repository can have additional dependencies on anything that helps demonstrate an example. Non trivial examples should have an accompanying README.md file.
The goal of examples is to demonstrate usage of rules_rust, not to test code.
Use //test for testing.
//test
Contains unit (in //test/unit) and integration tests. CI configuration is
stored in .bazelci.