1.. _module-pw_watch: 2 3.. rst-class:: with-subtitle 4 5======== 6pw_watch 7======== 8.. pigweed-module:: 9 :name: pw_watch 10 11 * **Automatically trigger build actions when source files change** 12 13---------- 14Background 15---------- 16In the web development space, file system watchers like `nodemon 17<https://www.npmjs.com/package/nodemon>`_ and `watchman 18<https://facebook.github.io/watchman/>`_ are prevalent. These watchers trigger 19actions when files change (such as reloading a web server), making development 20much faster. In the embedded space, file system watchers are less prevalent but 21no less useful! 22 23.. _module-pw_watch-design: 24 25------------ 26Our solution 27------------ 28``pw_watch`` is similar to file system watchers found in web development 29tooling but is focused around embedded development use cases. After changing 30source code, ``pw_watch`` can instantly compile, flash, and run tests. 31 32.. figure:: https://storage.googleapis.com/pigweed-media/pw_watch_test_demo2.gif 33 :width: 1420 34 :alt: ``pw watch`` running in fullscreen mode and displaying errors 35 36 ``pw watch`` running in fullscreen mode and displaying errors. 37 38Combined with the GN-based build which expresses the full dependency tree, 39only the exact tests affected by source changes are run. 40 41The demo below shows ``pw_watch`` building for a STMicroelectronics 42STM32F429I-DISC1 development board, flashing the board with the affected test, 43and verifying the test runs as expected. Once this is set up, you can attach 44multiple devices to run tests in a distributed manner to reduce the time it 45takes to run tests. 46 47.. figure:: https://storage.googleapis.com/pigweed-media/pw_watch_on_device_demo.gif 48 :width: 800 49 :alt: pw_watch running on-device tests 50 51.. _module-pw_watch-get-started: 52 53----------- 54Get started 55----------- 56 57GN 58== 59.. code-block:: bash 60 61 cd ~/pigweed 62 source activate.sh 63 pw watch 64 65The simplest way to get started with ``pw_watch`` is to launch it from a shell 66using the Pigweed environment as ``pw watch``. By default, ``pw_watch`` watches 67for repository changes and triggers the default Ninja build target at ``//out``. 68To override this behavior, provide the ``-C`` argument to ``pw watch``. 69 70See :ref:`module-pw_watch-guide` for more examples and 71:ref:`module-pw_watch-cli` for detailed CLI usage information. 72 73Bazel 74===== 75The Bazel build provides a ``//:watch`` entrypoint to ``pw_watch``, which 76executes commands with ``bazelisk``. Arguments are forwarded directly to 77``bazel`` / ``bazelisk``, so any ``bazel`` subcommands may be used. 78 79.. code-block:: sh 80 81 # Runs bazelisk build //... when files change. 82 bazelisk run //:watch build //... 83 84 # Runs an executable when files change. 85 bazelisk run //:watch -- run //important:script -a --value 52 86 87 # Builds //..., then runs the //foo:bar test. 88 bazelisk run //:watch build //... , test //foo:bar 89 90.. important:: 91 92 ``bazelisk run`` interprets arguments that start with ``-``. Pass ``--`` 93 before any other arguments to separate arguments to Bazel from command 94 arguments. 95 96 .. code-block:: sh 97 98 bazelisk run //:watch -- <commands to run> 99 100``//:watch`` is an alias of ``//pw_watch/py:bazel``. External projects may run 101this tool directly as ``@pigweed//:watch``, or create their own ``//:watch`` 102alias. 103 104Custom commands 105=============== 106.. automodule:: pw_watch.run 107 108.. toctree:: 109 :hidden: 110 :maxdepth: 1 111 112 guide 113 cli 114
