pw_watch#

pw_watch is similar to file system watchers found in web development tooling. These watchers trigger a web server reload on source file change, increasing iteration. In the embedded space, file system watchers are less prevalent but no less useful! The Pigweed watcher module makes it easy to instantly compile, flash, and run tests upon save.

pw watch running in fullscreen mode and displaying errors

pw watch running in fullscreen mode and displaying errors.#

pw watch Command Usage#

The simplest way to get started with pw_watch is to launch it from a shell using the Pigweed environment as pw watch. By default, pw_watch watches for repository changes and triggers the default Ninja build target at out/. To override this behavior, provide the -C argument to pw watch.

usage: pw watch [-h] [-C directory [target ...]]
                [--build-system-command directory command]
                [--run-command RUN_COMMAND] [-j JOBS] [-k] [--parallel]
                [--parallel-workers PARALLEL_WORKERS] [--logfile LOGFILE]
                [--separate-logfiles] [--debug-logging] [--banners]
                [--no-banners] [--colors] [--no-colors] [--patterns PATTERNS]
                [--ignore-patterns IGNORE_PATTERNS_STRING]
                [--exclude-list EXCLUDE_LIST [EXCLUDE_LIST ...]]
                [--no-restart] [--serve-docs]
                [--serve-docs-port SERVE_DOCS_PORT]
                [--serve-docs-path SERVE_DOCS_PATH] [-f]
                [target ...]

Build Directory and Command Options#

-C, --build-directory

Specify a build directory and optionally targets to build. pw watch -C out target1 target2 is equivalent to ‘ninja -C out taret1 target2’. The ‘out’ directory will be used if no others are provided.

Default: []

target

Default build targets. For example if the build directory is ‘out’ then, ‘ninja -C out taret1 target2’ will be run. To specify one or more directories, use the -C / --build-directory option.

Default: []

--build-system-command

Build system command for . Default: ninja

Default: []

--run-command

Additional commands to run. These are run before any -C arguments and may be repeated. For example: –run-command ‘bazel build //pw_cli/…’–run-command ‘bazel test //pw_cli/…’-C out python.lint python.test

Default: []

Build Execution Options#

-j, --jobs

Specify the number of cores to use for each build system.This is passed to ninja, bazel and make as “-j”

-k, --keep-going

Keep building past the first failure. This is equivalent to running “ninja -k 0” or “bazel build -k”.

--parallel

Run all builds in parallel.

--parallel-workers

How many builds may run at the same time when –parallel is enabled. Default: 0 meaning run all in parallel.

Default: 0

Log File Options#

--logfile

Global build output log file.

--separate-logfiles

Create separate log files per build directory.

--debug-logging

Enable Python build execution tool debug logging.

Display Output Options#

--banners

Show pass/fail banners.

--no-banners

Hide pass/fail banners.

--colors

Force color output from ninja.

--no-colors

Don’t force ninja to use color output.

Watch Options#

--patterns

Comma delimited list of globs to watch to trigger recompile.

Default: “.bloaty,.c,*.cc,*.css,*.cpp,*.cmake,CMakeLists.txt,*.dts,*.dtsi,*.gn,*.gni,*.go,*.h,*.hpp,*.ld,*.md,*.options,*.proto,*.py,*.rs,*.rst,*.s,*.S,*.toml”

--ignore-patterns

Comma delimited list of globs to ignore events from.

--exclude-list

Directories to ignore during pw watch. This option may be repeated. Directories are passed as separate arguments.

Default: []

--no-restart

do not restart ongoing builds if files change

--serve-docs

Start a webserver for docs on localhost. The port for this webserver can be set with the –serve-docs-port option. Defaults to http://127.0.0.1:8000

--serve-docs-port

Set the port for the docs webserver. Default: 8000.

Default: 8000

--serve-docs-path

Set the path for the docs to serve. Default: docs/gen/docs in the build directory.

Default: docs/gen/docs

-f, --fullscreen

Use a fullscreen interface.

Examples#

Ninja#

Build the default target in out/ using ninja.

pw watch -C out

Build python.lint and stm32f429i targets in out/ using ninja.

pw watch python.lint stm32f429i

Build the pw_run_tests.modules target in the out/cmake/ directory

pw watch -C out/cmake pw_run_tests.modules

Build the default target in out/ and pw_apps in out/cmake/

pw watch -C out -C out/cmake pw_apps

Build python.tests in out/ and pw_apps in out/cmake/

pw watch python.tests -C out/cmake pw_apps

Bazel#

Run bazel build followed by bazel test on the target //... using the out-bazel/ build directory.

pw watch --run-command 'mkdir -p out-bazel' \
  -C out-bazel '//...' \
  --build-system-command out-bazel 'bazel build' \
  --build-system-command out-bazel 'bazel test'

Log Files#

Run two separate builds simultaneously and stream the output to separate build log files. These log files are created:

  • out/build.txt: This will contain overall status messages and any sub build errors.

  • out/build_out.txt: Sub-build log only output for the out build directory:

  • out/build_outbazel.txt: Sub-build log only output for the outbazel build directory.

pw watch \
  --parallel \
  --logfile out/build.txt \
  --separate-logfiles \
  -C out default \
  -C outbazel '//...:all' \
  --build-system-command outbazel 'bazel build' \
  --build-system-command outbazel 'bazel test'

Including and Ignoring Files#

pw watch only rebuilds when a file that is not ignored by Git changes. Adding exclusions to a .gitignore causes watch to ignore them, even if the files were forcibly added to a repo. By default, only files matching certain extensions are applied, even if they’re tracked by Git. The --patterns and --ignore-patterns arguments can be used to include or exclude specific patterns. These patterns do not override Git’s ignoring logic.

The --exclude-list argument can be used to exclude directories from being watched. This decreases the number of files monitored with inotify in Linux.

Documentation Output#

When using --serve-docs, by default the docs will be rebuilt when changed, just like code files. However, you will need to manually reload the page in your browser to see changes. If you install the httpwatcher Python package into your Pigweed environment (pip install httpwatcher), docs pages will automatically reload when changed.

Disable Automatic Rebuilds#

pw watch automatically restarts an ongoing build when files change. This can be disabled with the --no-restart option. While running pw watch, you may also press enter to immediately restart a build.

Unit Test Integration#

Thanks to GN’s understanding of the full dependency tree, only the tests affected by a file change are run when pw_watch triggers a build. By default, host builds using pw_watch will run unit tests. To run unit tests on a device as part of pw_watch, refer to your device’s target documentation.