Wyatt Hepler | f9fb90f | 2020-09-30 18:59:33 -0700 | [diff] [blame] | 1 | .. _module-pw_watch: |
Armando Montanez | bcc194b | 2020-03-10 10:23:18 -0700 | [diff] [blame] | 2 | |
| 3 | -------- |
| 4 | pw_watch |
| 5 | -------- |
Armando Montanez | 0054a9b | 2020-03-13 13:06:24 -0700 | [diff] [blame] | 6 | ``pw_watch`` is similar to file system watchers found in the web development |
| 7 | space. These watchers trigger a web server reload on source change, increasing |
Armando Montanez | bcc194b | 2020-03-10 10:23:18 -0700 | [diff] [blame] | 8 | iteration. In the embedded space, file system watchers are less prevalent but no |
| 9 | less useful! The Pigweed watcher module makes it easy to instantly compile, |
| 10 | flash, and run tests upon save. |
| 11 | |
| 12 | .. image:: doc_resources/pw_watch_on_device_demo.gif |
| 13 | |
| 14 | .. note:: |
| 15 | |
Wyatt Hepler | c9e51d2 | 2020-10-29 09:12:37 -0700 | [diff] [blame] | 16 | ``pw_watch`` currently only works with Pigweed's GN and CMake builds. |
Armando Montanez | bcc194b | 2020-03-10 10:23:18 -0700 | [diff] [blame] | 17 | |
| 18 | Module Usage |
| 19 | ============ |
Armando Montanez | 0054a9b | 2020-03-13 13:06:24 -0700 | [diff] [blame] | 20 | The simplest way to get started with ``pw_watch`` is to launch it from a shell |
Wyatt Hepler | 00efe18 | 2020-11-23 08:25:14 -0800 | [diff] [blame] | 21 | using the Pigweed environment as ``pw watch``. By default, ``pw_watch`` watches |
Wyatt Hepler | d4a847e | 2021-09-10 18:16:33 -0700 | [diff] [blame] | 22 | for repository changes and triggers the default Ninja build target at out/. To |
| 23 | override this behavior, provide the ``-C`` argument to ``pw watch``. |
Armando Montanez | bcc194b | 2020-03-10 10:23:18 -0700 | [diff] [blame] | 24 | |
| 25 | .. code:: sh |
| 26 | |
Wyatt Hepler | d4a847e | 2021-09-10 18:16:33 -0700 | [diff] [blame] | 27 | # Use ./out/ as the build directory and build the default target |
Wyatt Hepler | 00efe18 | 2020-11-23 08:25:14 -0800 | [diff] [blame] | 28 | pw watch |
Armando Montanez | bcc194b | 2020-03-10 10:23:18 -0700 | [diff] [blame] | 29 | |
Wyatt Hepler | d4a847e | 2021-09-10 18:16:33 -0700 | [diff] [blame] | 30 | # Use ./out/ as the build directory and build the stm32f429i target |
Wyatt Hepler | 00efe18 | 2020-11-23 08:25:14 -0800 | [diff] [blame] | 31 | pw watch python.lint stm32f429i |
Armando Montanez | bcc194b | 2020-03-10 10:23:18 -0700 | [diff] [blame] | 32 | |
Wyatt Hepler | 00efe18 | 2020-11-23 08:25:14 -0800 | [diff] [blame] | 33 | # Build pw_run_tests.modules in the out/cmake directory |
| 34 | pw watch -C out/cmake pw_run_tests.modules |
Armando Montanez | bcc194b | 2020-03-10 10:23:18 -0700 | [diff] [blame] | 35 | |
Wyatt Hepler | 00efe18 | 2020-11-23 08:25:14 -0800 | [diff] [blame] | 36 | # Build the default target in out/ and pw_apps in out/cmake |
| 37 | pw watch -C out -C out/cmake pw_apps |
Armando Montanez | 7366d5a | 2020-06-17 15:04:43 -0700 | [diff] [blame] | 38 | |
Wyatt Hepler | d4a847e | 2021-09-10 18:16:33 -0700 | [diff] [blame] | 39 | # Build python.tests in out/ and build pw_apps in out/cmake |
Wyatt Hepler | 00efe18 | 2020-11-23 08:25:14 -0800 | [diff] [blame] | 40 | pw watch python.tests -C out/cmake pw_apps |
Armando Montanez | bcc194b | 2020-03-10 10:23:18 -0700 | [diff] [blame] | 41 | |
Wyatt Hepler | 6a0a649 | 2021-06-24 09:46:05 -0700 | [diff] [blame] | 42 | # Build the default target, but only run up to 8 jobs in parallel. |
| 43 | pw watch -j8 |
| 44 | |
Adam MacBeth | 9b3abb2 | 2021-07-15 17:58:55 +0000 | [diff] [blame] | 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 | |
Anthony DiGirolamo | 67e1d80 | 2022-01-29 13:46:31 -0800 | [diff] [blame] | 51 | # Build with a full screen terminal user interface similar to pw_console. |
| 52 | pw watch --fullscreen |
Elaine Hwang | e2dc38c | 2021-11-28 17:56:12 +0800 | [diff] [blame] | 53 | |
Wyatt Hepler | ea50056 | 2021-04-15 07:49:51 -0700 | [diff] [blame] | 54 | ``pw watch`` only rebuilds when a file that is not ignored by Git changes. |
| 55 | Adding exclusions to a ``.gitignore`` causes watch to ignore them, even if the |
| 56 | files were forcibly added to a repo. By default, only files matching certain |
| 57 | extensions are applied, even if they're tracked by Git. The ``--patterns`` and |
| 58 | ``--ignore_patterns`` arguments can be used to include or exclude specific |
| 59 | patterns. These patterns do not override Git's ignoring logic. |
Armando Montanez | bcc194b | 2020-03-10 10:23:18 -0700 | [diff] [blame] | 60 | |
Wyatt Hepler | ea50056 | 2021-04-15 07:49:51 -0700 | [diff] [blame] | 61 | The ``--exclude_list`` argument can be used to exclude directories from being |
| 62 | watched. This decreases the number of files monitored with inotify in Linux. |
Chenghan | c4c46b6 | 2020-05-08 17:43:23 -0400 | [diff] [blame] | 63 | |
Wyatt Hepler | 9e08015 | 2021-04-15 08:20:05 -0700 | [diff] [blame] | 64 | By default, ``pw watch`` automatically restarts an ongoing build when files |
| 65 | change. This can be disabled with the ``--no-restart`` option. While running |
| 66 | ``pw watch``, you may also press enter to immediately restart a build. |
Wyatt Hepler | f705151 | 2021-03-30 09:08:47 -0700 | [diff] [blame] | 67 | |
Wyatt Hepler | 6a0a649 | 2021-06-24 09:46:05 -0700 | [diff] [blame] | 68 | See ``pw watch -h`` for the full list of command line arguments. |
| 69 | |
Armando Montanez | bcc194b | 2020-03-10 10:23:18 -0700 | [diff] [blame] | 70 | Unit Test Integration |
| 71 | ===================== |
Armando Montanez | bcc194b | 2020-03-10 10:23:18 -0700 | [diff] [blame] | 72 | Thanks to GN's understanding of the full dependency tree, only the tests |
Armando Montanez | 0054a9b | 2020-03-13 13:06:24 -0700 | [diff] [blame] | 73 | affected by a file change are run when ``pw_watch`` triggers a build. By |
| 74 | default, host builds using ``pw_watch`` will run unit tests. To run unit tests |
| 75 | on a device as part of ``pw_watch``, refer to your device's |
Wyatt Hepler | f9fb90f | 2020-09-30 18:59:33 -0700 | [diff] [blame] | 76 | :ref:`target documentation<docs-targets>`. |