1.. _module-pw_watch:
2
3--------
4pw_watch
5--------
6``pw_watch`` is similar to file system watchers found in the web development
7space. These watchers trigger a web server reload on source change, increasing
8iteration. In the embedded space, file system watchers are less prevalent but no
9less useful! The Pigweed watcher module makes it easy to instantly compile,
10flash, and run tests upon save.
11
12.. image:: doc_resources/pw_watch_on_device_demo.gif
13
14.. note::
15
16  ``pw_watch`` currently only works with Pigweed's GN and CMake builds.
17
18Module Usage
19============
20The simplest way to get started with ``pw_watch`` is to launch it from a shell
21using the Pigweed environment as ``pw watch``. By default, ``pw_watch`` watches
22for repository changes and triggers the default Ninja build target for an
23automatically located build directory (typically ``$PW_ROOT/out``). To override
24this behavior, provide the ``-C`` argument to ``pw watch``.
25
26.. code:: sh
27
28  # Find a build directory and build the default target
29  pw watch
30
31  # Find a build directory and build the stm32f429i target
32  pw watch python.lint stm32f429i
33
34  # Build pw_run_tests.modules in the out/cmake directory
35  pw watch -C out/cmake pw_run_tests.modules
36
37  # Build the default target in out/ and pw_apps in out/cmake
38  pw watch -C out -C out/cmake pw_apps
39
40  # Find a directory and build python.tests, and build pw_apps in out/cmake
41  pw watch python.tests -C out/cmake pw_apps
42
43``pw watch`` only rebuilds when a file that is not ignored by Git changes.
44Adding exclusions to a ``.gitignore`` causes watch to ignore them, even if the
45files were forcibly added to a repo. By default, only files matching certain
46extensions are applied, even if they're tracked by Git. The ``--patterns`` and
47``--ignore_patterns`` arguments can be used to include or exclude specific
48patterns. These patterns do not override Git's ignoring logic.
49
50The ``--exclude_list`` argument can be used to exclude directories from being
51watched. This decreases the number of files monitored with inotify in Linux.
52
53By default, ``pw watch`` automatically restarts an ongoing build when files
54change. This can be disabled with the ``--no-restart`` option. While running
55``pw watch``, you may also press enter to immediately restart a build.
56
57Unit Test Integration
58=====================
59Thanks to GN's understanding of the full dependency tree, only the tests
60affected by a file change are run when ``pw_watch`` triggers a build. By
61default, host builds using ``pw_watch`` will run unit tests. To run unit tests
62on a device as part of ``pw_watch``, refer to your device's
63:ref:`target documentation<docs-targets>`.
64