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 at out/. To 23override this behavior, provide the ``-C`` argument to ``pw watch``. 24 25.. code:: sh 26 27 # Use ./out/ as the build directory and build the default target 28 pw watch 29 30 # Use ./out/ as the build directory and build the stm32f429i target 31 pw watch python.lint stm32f429i 32 33 # Build pw_run_tests.modules in the out/cmake directory 34 pw watch -C out/cmake pw_run_tests.modules 35 36 # Build the default target in out/ and pw_apps in out/cmake 37 pw watch -C out -C out/cmake pw_apps 38 39 # Build python.tests in out/ and build pw_apps in out/cmake 40 pw watch python.tests -C out/cmake pw_apps 41 42 # Build the default target, but only run up to 8 jobs in parallel. 43 pw watch -j8 44 45 # Build the default target and start a docs server on http://127.0.0.1:8000 46 pw watch --serve-docs 47 48 # Build the default target and start a docs server on http://127.0.0.1:5555 49 pw watch --serve-docs --serve-docs-port=5555 50 51 # Build with a full screen terminal user interface similar to pw_console. 52 pw watch --fullscreen 53 54``pw watch`` only rebuilds when a file that is not ignored by Git changes. 55Adding exclusions to a ``.gitignore`` causes watch to ignore them, even if the 56files were forcibly added to a repo. By default, only files matching certain 57extensions are applied, even if they're tracked by Git. The ``--patterns`` and 58``--ignore_patterns`` arguments can be used to include or exclude specific 59patterns. These patterns do not override Git's ignoring logic. 60 61The ``--exclude_list`` argument can be used to exclude directories from being 62watched. This decreases the number of files monitored with inotify in Linux. 63 64By default, ``pw watch`` automatically restarts an ongoing build when files 65change. This can be disabled with the ``--no-restart`` option. While running 66``pw watch``, you may also press enter to immediately restart a build. 67 68See ``pw watch -h`` for the full list of command line arguments. 69 70Unit Test Integration 71===================== 72Thanks to GN's understanding of the full dependency tree, only the tests 73affected by a file change are run when ``pw_watch`` triggers a build. By 74default, host builds using ``pw_watch`` will run unit tests. To run unit tests 75on a device as part of ``pw_watch``, refer to your device's 76:ref:`target documentation<docs-targets>`. 77
