1.. _module-pw_watch: 2 3======== 4pw_watch 5======== 6``pw_watch`` is similar to file system watchers found in web development 7tooling. These watchers trigger a web server reload on source file change, 8increasing iteration. In the embedded space, file system watchers are less 9prevalent but no less useful! The Pigweed watcher module makes it easy to 10instantly compile, flash, and run tests upon save. 11 12.. figure:: doc_resources/pw_watch_test_demo2.gif 13 :width: 1420 14 :alt: pw watch running in fullscreen mode and displaying errors 15 16 ``pw watch`` running in fullscreen mode and displaying errors. 17 18-------------------------- 19``pw watch`` Command Usage 20-------------------------- 21The simplest way to get started with ``pw_watch`` is to launch it from a shell 22using the Pigweed environment as ``pw watch``. By default, ``pw_watch`` watches 23for repository changes and triggers the default Ninja build target at out/. To 24override this behavior, provide the ``-C`` argument to ``pw watch``. 25 26.. argparse:: 27 :module: pw_watch.watch 28 :func: get_parser 29 :prog: pw watch 30 :nodefaultconst: 31 :nodescription: 32 :noepilog: 33 34-------- 35Examples 36-------- 37 38Ninja 39===== 40Build the default target in ``out/`` using ``ninja``. 41 42.. code-block:: sh 43 44 pw watch -C out 45 46Build ``python.lint`` and ``stm32f429i`` targets in ``out/`` using ``ninja``. 47 48.. code-block:: sh 49 50 pw watch python.lint stm32f429i 51 52Build the ``pw_run_tests.modules`` target in the ``out/cmake/`` directory 53 54.. code-block:: sh 55 56 pw watch -C out/cmake pw_run_tests.modules 57 58Build the default target in ``out/`` and ``pw_apps`` in ``out/cmake/`` 59 60.. code-block:: sh 61 62 pw watch -C out -C out/cmake pw_apps 63 64Build ``python.tests`` in ``out/`` and ``pw_apps`` in ``out/cmake/`` 65 66.. code-block:: sh 67 68 pw watch python.tests -C out/cmake pw_apps 69 70Bazel 71===== 72Run ``bazel build`` followed by ``bazel test`` on the target ``//...`` using the 73``out-bazel/`` build directory. 74 75.. code-block:: sh 76 77 pw watch --run-command 'mkdir -p out-bazel' \ 78 -C out-bazel '//...' \ 79 --build-system-command out-bazel 'bazel build' \ 80 --build-system-command out-bazel 'bazel test' 81 82Log Files 83========= 84Run two separate builds simultaneously and stream the output to separate build 85log files. These log files are created: 86 87- ``out/build.txt``: This will contain overall status messages and any sub build 88 errors. 89- ``out/build_out.txt``: Sub-build log only output for the ``out`` build 90 directory: 91- ``out/build_outbazel.txt``: Sub-build log only output for the ``outbazel`` 92 build directory. 93 94.. code-block:: sh 95 96 pw watch \ 97 --parallel \ 98 --logfile out/build.txt \ 99 --separate-logfiles \ 100 -C out default \ 101 -C outbazel '//...:all' \ 102 --build-system-command outbazel 'bazel build' \ 103 --build-system-command outbazel 'bazel test' 104 105Including and Ignoring Files 106============================ 107``pw watch`` only rebuilds when a file that is not ignored by Git changes. 108Adding exclusions to a ``.gitignore`` causes watch to ignore them, even if the 109files were forcibly added to a repo. By default, only files matching certain 110extensions are applied, even if they're tracked by Git. The ``--patterns`` and 111``--ignore-patterns`` arguments can be used to include or exclude specific 112patterns. These patterns do not override Git's ignoring logic. 113 114The ``--exclude-list`` argument can be used to exclude directories from being 115watched. This decreases the number of files monitored with inotify in Linux. 116 117Documentation Output 118==================== 119When using ``--serve-docs``, by default the docs will be rebuilt when changed, 120just like code files. However, you will need to manually reload the page in 121your browser to see changes. If you install the ``httpwatcher`` Python package 122into your Pigweed environment (``pip install httpwatcher``), docs pages will 123automatically reload when changed. 124 125Disable Automatic Rebuilds 126========================== 127``pw watch`` automatically restarts an ongoing build when files 128change. This can be disabled with the ``--no-restart`` option. While running 129``pw watch``, you may also press enter to immediately restart a build. 130 131--------------------- 132Unit Test Integration 133--------------------- 134Thanks to GN's understanding of the full dependency tree, only the tests 135affected by a file change are run when ``pw_watch`` triggers a build. By 136default, host builds using ``pw_watch`` will run unit tests. To run unit tests 137on a device as part of ``pw_watch``, refer to your device's 138:ref:`target documentation<docs-targets>`. 139 140
