1.. _module-pw_watch-guide: 2 3============ 4How-to guide 5============ 6.. pigweed-module-subpage:: 7 :name: pw_watch 8 9This guide shows you how to do common ``pw_watch`` tasks. 10 11See :ref:`docs-build-system` for an overview of Pigweed's approach to build 12systems. 13 14------------------------------- 15Set up your Pigweed environment 16------------------------------- 17See :ref:`activate-pigweed-environment` if you see an error like this: 18 19.. code-block:: console 20 21 $ pw watch 22 bash: pw: command not found 23 24----- 25Ninja 26----- 27This section contains common use cases for :ref:`docs-build-system-gn` 28users. 29 30.. _module-pw_watch-guide-ninja-custom-dirs: 31 32Set up a custom build directory 33------------------------------- 34 35Before running any command that uses a custom build directory, you need to 36run ``gn gen <dir>``, where ``<dir>`` is a placeholder for the name of your 37custom build directory. 38 39For example, before running this command: 40 41.. code-block:: console 42 43 $ pw watch -C out2 44 45You need to run this command: 46 47.. code-block:: console 48 49 $ gn gen out2 50 51Build the default target and use the default build directory 52------------------------------------------------------------ 53.. code-block:: console 54 55 $ pw watch 56 57The default build directory is ``out``. 58 59Customize the build directory 60----------------------------- 61This section assumes you have completed 62:ref:`module-pw_watch-guide-ninja-custom-dirs`. 63 64.. code-block:: console 65 66 $ pw watch -C out2 67 68This builds the default target in ``out2``. 69 70Build two targets 71----------------- 72.. code-block:: console 73 74 $ pw watch stm32f429i python.lint 75 76The ``stm32f429i`` and ``python.lint`` targets are both built in the default 77build directory (``out``). 78 79Build the same target in different build directories 80---------------------------------------------------- 81This section assumes you have completed 82:ref:`module-pw_watch-guide-ninja-custom-dirs`. 83 84.. code-block:: console 85 86 $ pw watch -C out1 -C out2 87 88This example builds the default target in both ``out1`` and ``out2``. 89 90Build different targets in different build directories 91------------------------------------------------------ 92This section assumes you have completed 93:ref:`module-pw_watch-guide-ninja-custom-dirs`. 94 95.. code-block:: console 96 97 $ pw watch stm32f429i -C out2 python.lint 98 99The ``stm32f429i`` target is built in the default build directory (``out``). 100The ``python.lint`` target is built in the custom build directory (``out2``). 101 102Unit test integration 103--------------------- 104Thanks to GN's understanding of the full dependency tree, only the tests 105affected by a file change are run when ``pw_watch`` triggers a build. By 106default, host builds using ``pw_watch`` will run unit tests. To run unit tests 107on a device as part of ``pw_watch``, refer to your device's 108:ref:`target documentation<docs-targets>`. 109 110---------------------------- 111Build-system-agnostic guides 112---------------------------- 113This section discusses general use cases that all apply to all ``pw watch`` 114usage. In other words, these use cases are not affected by whether you're 115using GN, Bazel, and so on. 116 117Ignore files 118------------ 119``pw watch`` only rebuilds when a file that is not ignored by Git changes. 120Adding exclusions to a ``.gitignore`` causes ``pw watch`` to ignore them, even 121if the files were forcibly added to a repo. By default, only files matching 122certain extensions are applied, even if they're tracked by Git. The 123``--patterns`` and ``--ignore-patterns`` arguments can be used to include or 124exclude specific patterns. These patterns do not override Git's ignoring logic. 125 126The ``--exclude-list`` argument can be used to exclude directories from being 127watched. This decreases the number of files monitored with ``inotify`` in Linux. 128 129Automatically reload docs 130------------------------- 131When using ``--serve-docs``, by default the docs will be rebuilt when changed, 132just like code files. However, you will need to manually reload the page in 133your browser to see changes. 134 135Disable automatic rebuilds 136-------------------------- 137``pw watch`` automatically restarts an ongoing build when files change. This 138can be disabled with the ``--no-restart`` option. While running ``pw watch``, 139you may also press :kbd:`Enter` to immediately restart a build. 140