| .. _module-pw_watch: | |
| -------- | |
| pw_watch | |
| -------- | |
| ``pw_watch`` is similar to file system watchers found in the web development | |
| space. These watchers trigger a web server reload on source 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. | |
| .. image:: doc_resources/pw_watch_on_device_demo.gif | |
| .. note:: | |
| ``pw_watch`` currently only works with Pigweed's GN and CMake builds. | |
| Module 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``. | |
| .. code:: sh | |
| # Use ./out/ as the build directory and build the default target | |
| pw watch | |
| # Use ./out/ as the build directory and build the stm32f429i target | |
| pw watch python.lint stm32f429i | |
| # Build pw_run_tests.modules 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 build pw_apps in out/cmake | |
| pw watch python.tests -C out/cmake pw_apps | |
| # Build the default target, but only run up to 8 jobs in parallel. | |
| pw watch -j8 | |
| # Build the default target and start a docs server on http://127.0.0.1:8000 | |
| pw watch --serve-docs | |
| # Build the default target and start a docs server on http://127.0.0.1:5555 | |
| pw watch --serve-docs --serve-docs-port=5555 | |
| ``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. | |
| By default, ``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. | |
| See ``pw watch -h`` for the full list of command line arguments. | |
| 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 | |
| :ref:`target documentation<docs-targets>`. |