Build systems reference#
This is a reference of commands that you may need when working with the build systems of Upstream Pigweed.
Bazel#
See also 0111: Make Bazel Pigweed’s Primary Build System, Bazel style, Bazel, Bazel build system integrations, and Bazel build compatibility patterns.
Build#
Build everything#
$ bazelisk build //...
Bazel automatically downloads and sets up all dependencies. You don’t need to manually install cross-platform toolchains, set up virtual environments, etc.
Build a single target#
Inspect a
BUILD.bazel
file to find the name of the target you want to build. For example, in//pw_containers/BUILD.bazel
the target for building pw::Vector is calledvector
.Build that target:
$ bazelisk build //pw_containers:vector
Tip
The main target for a Pigweed module always
matches the name of the module. E.g. within //pw_bytes/BUILD.bazel
the
main target is called pw_bytes
. You can build that target with
bazelisk build //pw_bytes:pw_bytes
. When the target name matches the
directory name, you can omit the target name and shorten the command to this:
bazelisk build //pw_bytes
Build for a specific hardware platform#
$ bazelisk build --config=rp2040 //...
The value for --config
should be one of the directory names listed in
//targets.
Automatically rebuild when files change#
$ bazelisk run //:watch build //...
pw_watch lets you automatically rebuild the code when files change.
Tip
You can use whatever command you like after bazelisk run //:watch
. For
example, if you only wanted to rebuild a single target,
you can instead run a command like this:
bazelisk run //:watch build //pw_containers:vector
Build the docs#
Simultaneously build the docs and spin up a local server so that you can preview the docs in a web browser:
$ bazelisk run //docs:docs.serve
See Working with the pigweed.dev build system for more docs-related workflows and Docs contributors for guidance about authoring docs.
Test#
Run all tests#
$ bazelisk test //...
Run a single test#
Inspect a
BUILD.bazel
file to find the name of the test you want to run. For example, within//pw_varint/BUILD.bazel
there is a test calledstream_test
.Run that test:
$ bazelisk test //pw_varint:stream_test
Run on-device tests#
On-device tests are only supported for the Raspberry Pi RP2040. See Run on-device tests.
GN#
See also GN / Ninja, GN build system integrations, and Pigweed’s GN Python Build.
Bootstrap the Pigweed environment#
$ . bootstrap.sh
$ . bootstrap.fish
$ bootstrap.bat
Example:

Activate the Pigweed environment#
$ . activate.sh
$ . activate.fish
$ activate.bat
You don’t need to bootstrap before every development session. You can instead re-activate your previously bootstrapped environment, which in general is much faster.
Configure the GN build#
$ gn gen out
Watch#
$ pw watch
pw watch
automatically rebuilds the code and re-runs tests when files change.
Example:

Watch one target#
$ pw watch stm32f429i
See also Hardware targets.
Build#
Build everything#
To build everything:
$ ninja -C out
Note
out
is simply the directory the build files are saved to. Unless
this directory is deleted or you desire to do a clean build, there’s no need
to run GN again; just rebuild using Ninja directly.
Warning
Unless your build directory (the out
in gn gen out
) is exactly one
directory away from the project root directory (the Pigweed repo root in this
case), there will be issues finding source files while debugging and while
generating coverage reports. This is due an issue in upstream LLVM reordering
debug and coverage path mappings. See b/278898014 and b/278906020.
Build one target#
$ ninja -C out stm32f429i
See also Hardware targets.
Build only the docs#
$ ninja -C out docs
The generated docs are output to //out/docs/gen/docs/html
.
Build tests individually#
Use gn outputs
to translate a GN build step into a Ninja build step. Append
the GN path to the target toolchain in parentheses, after
the desired build step label.
$ gn outputs out "//pw_status:status_test.run(//targets/host/pigweed_internal:pw_strict_host_clang_debug)"
pw_strict_host_clang_debug/obj/pw_status/status_test.run.pw_pystamp
$ ninja -C out pw_strict_host_clang_debug/obj/pw_status/status_test.run.pw_pystamp
ninja: Entering directory `out'
[4/4] ACTION //pw_status:status_test.run(//targets/host/pigweed_internal:pw_strict_host_clang_debug)
The .run
following the test target name is a sub-target created as part of
the pw_test
GN template. If you remove .run
, the test will build but
not attempt to run.
In macOS and Linux, xargs
can be used to turn this into a single command:
$ gn outputs out "//pw_status:status_test.run(//targets/host/pigweed_internal:pw_strict_host_clang_debug)" | xargs ninja -C out
Test#
Run all tests#
pw watch automatically runs tests. Example:

Manually run an invididual test#
$ ./out/pw_strict_host_clang_debug/obj/pw_status/test/status_test
Run tests on-device#
See Testing.