pw_watch how-to guide#
Pigweed AI summary: This guide provides instructions for common tasks using the pw_watch tool, which is an embedded development file system watcher. It includes sections on setting up a Pigweed environment, using the Ninja build system, customizing build directories, and unit test integration. Additionally, there are build-system-agnostic guides on ignoring files, automatically reloading docs, and disabling automatic rebuilds.
This guide shows you how to do common pw_watch tasks.
See Build system for an overview of Pigweed’s approach to build systems.
Set up your Pigweed environment#
Pigweed AI summary: This paragraph provides instructions on how to set up a Pigweed environment and includes a reference to a guide for activating the environment if an error message is encountered.
See Activate your Pigweed Environment if you see an error like this:
pw watch
bash: pw: command not found
Ninja#
Pigweed AI summary: This section provides common use cases for GN users. It explains how to set up a custom build directory, build the default target and use the default build directory, customize the build directory, build two targets, build the same target in different build directories, build different targets in different build directories, and integrate unit testing. GN's understanding of the full dependency tree allows for only affected tests to be run during a build triggered by pw_watch. Host builds using pw_watch will run unit tests by default, but
This section contains common use cases for GN users.
Set up a custom build directory#
Pigweed AI summary: To use a custom build directory, you must first run the command "gn gen <dir>" where <dir> is the name of your custom build directory. This must be done before running any command that uses the custom build directory, such as "pw watch -C out2".
Before running any command that uses a custom build directory, you need to
run gn gen <dir>, where <dir> is a placeholder for the name of your
custom build directory.
For example, before running this command:
pw watch -C out2
You need to run this command:
gn gen out2
Build the default target and use the default build directory#
Pigweed AI summary: To build the default target and use the default build directory, simply run the command "pw watch". The default build directory is named "out".
pw watch
The default build directory is out.
Customize the build directory#
Pigweed AI summary: This section discusses how to customize the build directory assuming that the user has already set up a custom build directory. The command "pw watch -C out2" is used to build the default target in the specified directory "out2".
This section assumes you have completed Set up a custom build directory.
pw watch -C out2
This builds the default target in out2.
Build two targets#
Pigweed AI summary: This paragraph explains that the targets "stm32f429i" and "python.lint" are both built in the default build directory "out" when the command "pw watch stm32f429i python.lint" is executed.
pw watch stm32f429i python.lint
The stm32f429i and python.lint targets are both built in the default
build directory (out).
Build the same target in different build directories#
Pigweed AI summary: This section explains how to build the same target in different build directories using the command "pw watch -C out1 -C out2". It assumes that the user has already set up a custom build directory. The example provided shows how to build the default target in both "out1" and "out2".
This section assumes you have completed Set up a custom build directory.
pw watch -C out1 -C out2
This example builds the default target in both out1 and out2.
Build different targets in different build directories#
Pigweed AI summary: This section discusses building different targets in different build directories, assuming that the user has already set up a custom build directory. It provides an example command for building the "stm32f429i" target in the default build directory and the "python.lint" target in the custom build directory.
This section assumes you have completed Set up a custom build directory.
pw watch stm32f429i -C out2 python.lint
The stm32f429i target is built in the default build directory (out).
The python.lint target is built in the custom build directory (out2).
Unit test integration#
Pigweed AI summary: GN's understanding of the full dependency tree allows for only the necessary tests to be run when a file change occurs and pw_watch triggers a build. Host builds using pw_watch will run unit tests by default, but to run unit tests on a device as part of pw_watch, refer to the device's target documentation.
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.
Build-system-agnostic guides#
Pigweed AI summary: This section provides general use cases for using "pw watch" that apply to all build systems, such as ignoring files using ".gitignore", excluding directories from being watched, automatically reloading docs when changed, and disabling automatic rebuilds. The "pw watch" tool automatically restarts an ongoing build when files change, but this can be disabled with the "--no-restart" option.
This section discusses general use cases that all apply to all pw watch
usage. In other words, these use cases are not affected by whether you’re
using GN, Bazel, and so on.
Ignore files#
Pigweed AI summary: This paragraph explains how the "pw watch" command only rebuilds when a file that is not ignored by Git changes. It also mentions that adding exclusions to a .gitignore file will cause "pw watch" to ignore them, even if the files were forcibly added to a repo. Additionally, it notes that only files matching certain extensions are applied by default, but the "--patterns" and "--ignore-patterns" arguments can be used to include or exclude specific patterns. The "--exclude-list"
pw watch only rebuilds when a file that is not ignored by Git changes.
Adding exclusions to a .gitignore causes pw 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.
Automatically reload docs#
Pigweed AI summary: When using the "--serve-docs" command, the documentation will be rebuilt automatically when changes are made. However, the page must be manually reloaded in the browser to see the changes. To avoid this, the "httpwatcher" Python package can be installed in the Pigweed environment, which will automatically reload the documentation pages when changes are made.
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#
Pigweed AI summary: The "pw watch" command automatically restarts a build when files are changed, but this feature can be disabled with the "--no-restart" option. Additionally, while running "pw watch," pressing the "Enter" key will immediately restart a build.
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.