mirror of https://github.com/bazelbuild/rules_rust
59 lines
2.6 KiB
Markdown
59 lines
2.6 KiB
Markdown
# 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](https://github.com/bazelbuild/rules_rust/issues/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.
|