1# Rules Rust - Architecture 2 3In this file we describe how we think about the architecture 4of `rules_rust`. Its goal is to help contributors orient themselves, and to 5document code restrictions and assumptions. 6 7In general we try to follow the common standard defined by 8https://docs.bazel.build/versions/master/skylark/deploying.html. 9 10## //rust 11 12This is the core package of the rules. It contains all the core rules such as 13`rust_binary` and `rust_library`. It also contains `rust_common`, a Starlark 14struct providing all rules_rust APIs that one might need when writing custom 15rules integrating with rules_rust. 16 17`//rust` and all its subpackages have to be standalone. Users who only need 18the core rules should be able to ignore all other packages. 19 20`//rust:defs.bzl` is the file that all users of `rules_rust` will be using. 21Everything in this file can be used (depended on) and is supported (though 22stability is not currently guaranteed across commits, see 23[#600](https://github.com/bazelbuild/rules_rust/issues/600)). Typically this 24file re-exports definitions from other files, typically from `//rust/private`. 25Also other packages in `rules_rust` should access core rules through the public 26API only. We expect dogfooding our own APIs increases their 27quality. 28 29`//rust/private` package contains code for rule implementation. This file can only 30depend on `//rust` and its subpackages. Exceptions are Bazel's builtin packages 31and public APIs of other rules (such as `rules_cc`). Depending on 32`//rust/private` from packages other than `//rust` is not supported, we reserve 33the right to change anything there and not tell anybody. 34 35When core rules need custom tools (such as process wrapper, launcher, test 36runner, and so on), they should be stored in `//rust/tools` (for public tools) 37or in `//rust/private/tools` (for private tools). These should: 38 39* be essential (it does not make sense to have core rules without them) 40* have few or no third party dependencies, and their third party dependencies 41 should be checked in. 42* be usable for cross compilation 43* have only essential requirements on the host system (requiring that a custom 44 library is installed on the system is frowned upon) 45 46## //examples (@examples) 47 48Examples package is actually a local repository. This repository can have 49additional dependencies on anything that helps demonstrate an example. Non 50trivial examples should have an accompanying README.md file. 51 52The goal of examples is to demonstrate usage of `rules_rust`, not to test code. 53Use `//test` for testing. 54 55## //test 56 57Contains unit (in `//test/unit`) and integration tests. CI configuration is 58stored in .bazelci. 59