1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
|
.. _module-pw_watch:
========
pw_watch
========
``pw_watch`` is similar to file system watchers found in web development
tooling. These watchers trigger a web server reload on source file 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.
.. figure:: doc_resources/pw_watch_test_demo2.gif
:width: 1420
:alt: pw watch running in fullscreen mode and displaying errors
``pw watch`` running in fullscreen mode and displaying errors.
--------------------------
``pw watch`` Command 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``.
.. argparse::
:module: pw_watch.watch
:func: get_parser
:prog: pw watch
:nodefaultconst:
:nodescription:
:noepilog:
--------
Examples
--------
Ninja
=====
Build the default target in ``out/`` using ``ninja``.
.. code-block:: sh
pw watch -C out
Build ``python.lint`` and ``stm32f429i`` targets in ``out/`` using ``ninja``.
.. code-block:: sh
pw watch python.lint stm32f429i
Build the ``pw_run_tests.modules`` target in the ``out/cmake/`` directory
.. code-block:: sh
pw watch -C out/cmake pw_run_tests.modules
Build the default target in ``out/`` and ``pw_apps`` in ``out/cmake/``
.. code-block:: sh
pw watch -C out -C out/cmake pw_apps
Build ``python.tests`` in ``out/`` and ``pw_apps`` in ``out/cmake/``
.. code-block:: sh
pw watch python.tests -C out/cmake pw_apps
Bazel
=====
Run ``bazel build`` followed by ``bazel test`` on the target ``//...`` using the
``out-bazel/`` build directory.
.. code-block:: sh
pw watch --run-command 'mkdir -p out-bazel' \
-C out-bazel '//...' \
--build-system-command out-bazel 'bazel build' \
--build-system-command out-bazel 'bazel test'
Log Files
=========
Run two separate builds simultaneously and stream the output to separate build
log files. These log files are created:
- ``out/build.txt``: This will contain overall status messages and any sub build
errors.
- ``out/build_out.txt``: Sub-build log only output for the ``out`` build
directory:
- ``out/build_outbazel.txt``: Sub-build log only output for the ``outbazel``
build directory.
.. code-block:: sh
pw watch \
--parallel \
--logfile out/build.txt \
--separate-logfiles \
-C out default \
-C outbazel '//...:all' \
--build-system-command outbazel 'bazel build' \
--build-system-command outbazel 'bazel test'
Including and Ignoring Files
============================
``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.
Documentation Output
====================
When using ``--serve-docs``, by default the docs will be rebuilt when changed,
just like code files. However, you will need to manually reload the page in
your browser to see changes. If you install the ``httpwatcher`` Python package
into your Pigweed environment (``pip install httpwatcher``), docs pages will
automatically reload when changed.
Disable Automatic Rebuilds
==========================
``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.
---------------------
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>`.
|
