Build systems reference#

This is a reference of commands that you may need when working with the build systems of Upstream Pigweed.

Bazel#

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 called vector.

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 called stream_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#

Bootstrap the Pigweed environment#

Bash

$ . bootstrap.sh

Fish

$ . bootstrap.fish

Windows

$ bootstrap.bat

Example:

Activate the Pigweed environment#

Bash

$ . activate.sh

Fish

$ . activate.fish

Windows

$ 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

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

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.