The OpenPRoT Technical Charter can be found at https://github.com/OpenPRoT/.github/blob/main/GOVERNANCE.md
NOTE: We are converting our build system to bazel. We recommend installing bazelisk to automatically manage bazel versions.
You can run tasks using the Pigweed workflow launcher pw or bazel.
./pw presubmit- Run presubmit checks: formatting, license checks, C/C++ header checks andclippy../pw format- Run the code formatters.bazel test //...- Run all tests.bazel build //docs- Build documentation.bazel run //:watch build //docs- Rebuild documentation when files change../pw watch build //docsdoes the same.bazel run //docs:serve- Serve documentation onhttp://localhost:8000.
The project is structured as a bazel module.
Release firmware is published with signed SLSA build provenance. See docs/src/supply-chain.md for how to verify it.
No additional tools are required to build and test - all dependencies are managed by bazel. The sections below are optional and only describe editor setup.
-
Rust toolchain and rust-analyzer. Builds do not use
rustup, but the editor does. Install rustup. The repository'srust-toolchain.tomlpins the nightly channel and lists therust-analyzer,rust-src,rustfmtandclippycomponents, so rustup installs them automatically the first timerustcorcargoruns in the repository. To install them eagerly (or to add the component to an older checkout), run:rustup show # installs the pinned toolchain + components rustup component add rust-analyzer # only if it is missing
-
Buildifier formats
BUILD.bazel/.bzlfiles. Download a prebuilt binary from the buildtools releases and put it on yourPATH(usebuildifier-linux-arm64on ARM Linux, orbuildifier-darwin-amd64/buildifier-darwin-arm64on macOS):sudo curl -fsSL -o /usr/local/bin/buildifier \ https://github.com/bazelbuild/buildtools/releases/latest/download/buildifier-linux-amd64 sudo chmod +x /usr/local/bin/buildifier buildifier --version
Alternatively,
go install github.com/bazelbuild/buildtools/buildifier@latest../pw formatalso runs buildifier, so the editor tool is only for format-on-save.
- Bazel
(
BazelBuild.vscode-bazel): Starlark syntax, target browsing, and buildifier integration. - rust-analyzer
(
rust-lang.rust-analyzer).
There is no Cargo workspace, so rust-analyzer gets its crate graph from a generated
rust-project.json (git-ignored) at the repository root:
bazel run @rules_rust//tools/rust_analyzer:gen_rust_projectThis covers //..., which is large (hundreds of crates) and can use more than 10 GB of
memory in rust-analyzer, which may get it killed on small machines or WSL. Prefer
generating for only the targets you are working on:
bazel run @rules_rust//tools/rust_analyzer:gen_rust_project -- \
//services/orchestrator/... //drivers/usart/...Crates that only build for an embedded target (those with
target_compatible_with = TARGET_COMPATIBLE_WITH, e.g. everything under
target/ast10x0/) are skipped when generating for the host, so their files get no
highlighting or hover. Pass the target's Bazel config to the generator's inner build
with --config:
bazel run @rules_rust//tools/rust_analyzer:gen_rust_project -- \
--config=virt_ast10x0 //target/ast10x0/peripherals:peripheralsThe same applies to Earl Grey:
bazel run @rules_rust//tools/rust_analyzer:gen_rust_project -- \
--config=k_earlgrey //target/earlgrey/...If a file has no highlighting, hover or go-to-definition, its crate is most likely not
in rust-project.json. Check, in order:
-
Is the target listed? Search
rust-project.jsonfor the crate name or file path. If it is missing, add the target (or a parent package such as//path/to/pkg/...) to thegen_rust_projectcommand. Remember that each run overwrites the file. -
Is it embedded-only? If the target uses
target_compatible_with, it is skipped on the host platform, with no error. Pass the config that selects its platform after the--. The configs are defined in.bazelrc:Directory Config target/ast10x0/--config=virt_ast10x0target/earlgrey/--config=k_earlgreytarget/veer/--config=k_veer -
No config exists for your target? Add one to
.bazelrcnext to the existing ones. It must use thecommon:prefix, not justbuild:, so the setting also reaches the generator's inner build:common:k_mytarget --platforms=//target/mytarget:mytarget build:k_mytarget --build_tag_filters=-do_not_build,-kernel_doc_test -
Reload. After regenerating, run "rust-analyzer: Reload Workspace". Double-check the spelling of the command and config names, since a typo in either fails the run.
Notes:
- Put
--configafter the--. Using--platformsonbazel runitself builds the generator for the embedded target and fails. - Each run overwrites
rust-project.json, so list every target you need in one command. - Regenerate after adding crates or changing dependencies, then run "rust-analyzer: Reload Workspace".
.vscode/settings.json is git-ignored, so each developer keeps their own copy. A
suggested starting point:
{
"rust-analyzer.workspace.discoverConfig": {
"command": [
"bazel", "run",
"--noshow_progress", "--noshow_loading_progress", "--show_result=0",
"--ui_event_filters=-info,-warning,-debug", "--curses=no", "--color=no",
"@rules_rust//tools/rust_analyzer:discover_bazel_rust_project", "--",
"--bazel_arg=--config=virt_ast10x0"
],
"progressLabel": "bazel",
"filesToWatch": ["BUILD", "BUILD.bazel", "MODULE.bazel", "*.bzl"]
},
"rust-analyzer.cachePriming.enable": false,
"rust-analyzer.numThreads": 4,
"rust-analyzer.checkOnSave": true,
"rust-analyzer.check.overrideCommand": [
"bazel", "build", "--keep_going", "--config=virt_ast10x0",
"--@rules_rust//:error_format=json",
"--noshow_progress", "--ui_event_filters=-info,-warning,-debug",
"//target/ast10x0/..."
],
"rust-analyzer.files.exclude": ["third_party/**", "bazel-*/**"],
"bazel.buildifier.executable": "/usr/local/bin/buildifier",
"bazel.codeLens.enable": true,
"[rust]": {
"editor.defaultFormatter": "rust-lang.rust-analyzer",
"editor.formatOnSave": true
},
"[starlark]": {
"editor.defaultFormatter": "BazelBuild.vscode-bazel",
"editor.formatOnSave": true
}
}discoverConfigmakes rust-analyzer ask Bazel for the crate graph, so you do not need to generaterust-project.jsonby hand. The--bazel_argand--ui_event_filtersflags matter: rust-analyzer parses every line the command prints as JSON, so any Bazel progress output on stderr makes discovery fail withexpected value. Rerunninggen_rust_project(step 3) and setting"rust-analyzer.linkedProjects": ["rust-project.json"]instead is still supported.- Without an argument, discovery covers
//...under the given config, which is large (see the memory note in step 3). If it is too heavy, append"{arg}"to the command so rust-analyzer discovers only the package of the file you open. checkOnSaveandcheck.overrideCommandshow compiler errors inline. rust-analyzer needs--@rules_rust//:error_format=jsonso rustc emits machine-readable diagnostics. This builds the whole target tree on every save, so narrow the label (e.g.//target/ast10x0/peripherals/...) if it is slow.cachePriming.enable,numThreadsandfiles.excludelimit rust-analyzer's memory use; relax them if your machine has plenty of RAM.- Set
bazel.buildifier.executableto the output ofwhich buildifier. [rust]formats on save with rustfmt, which the pinned toolchain inrust-toolchain.tomlprovides. Run "Format Document" once to confirm it works.
Use the config for your target. --config=virt_ast10x0 appears twice above, in
discoverConfig (as --bazel_arg=--config=...) and in check.overrideCommand. Change both
to the config for the code you work on, and change the label in check.overrideCommand to
match. The configs are listed in the table in step 3 and defined in .bazelrc; for
example, use k_earlgrey and //target/earlgrey/... for Earl Grey. Without the right
config, crates that only build for an embedded target are skipped with no error, so their
files get no highlighting or diagnostics. After changing either command, run
"rust-analyzer: Restart server".