.. _module-pw_watch-guide:

============
How-to guide
============
.. pigweed-module-subpage::
   :name: pw_watch

This guide shows you how to do common ``pw_watch`` tasks.

See :ref:`docs-build-system` for an overview of Pigweed's approach to build
systems.

-------------------------------
Set up your Pigweed environment
-------------------------------
See :ref:`activate-pigweed-environment` if you see an error like this:

.. code-block:: console

   $ pw watch
   bash: pw: command not found

-----
Ninja
-----
This section contains common use cases for :ref:`docs-build-system-gn`
users.

.. _module-pw_watch-guide-ninja-custom-dirs:

Set up a custom build directory
-------------------------------

Before running any command that uses a custom build directory, you need to
run ``gn gen <dir>``, where ``<dir>`` is a placeholder for the name of your
custom build directory.

For example, before running this command:

.. code-block:: console

   $ pw watch -C out2

You need to run this command:

.. code-block:: console

   $ gn gen out2

Build the default target and use the default build directory
------------------------------------------------------------
.. code-block:: console

   $ pw watch

The default build directory is ``out``.

Customize the build directory
-----------------------------
This section assumes you have completed
:ref:`module-pw_watch-guide-ninja-custom-dirs`.

.. code-block:: console

   $ pw watch -C out2

This builds the default target in ``out2``.

Build two targets
-----------------
.. code-block:: console

   $ pw watch stm32f429i python.lint

The ``stm32f429i`` and ``python.lint`` targets are both built in the default
build directory (``out``).

Build the same target in different build directories
----------------------------------------------------
This section assumes you have completed
:ref:`module-pw_watch-guide-ninja-custom-dirs`.

.. code-block:: console

   $ pw watch -C out1 -C out2

This example builds the default target in both ``out1`` and ``out2``.

Build different targets in different build directories
------------------------------------------------------
This section assumes you have completed
:ref:`module-pw_watch-guide-ninja-custom-dirs`.

.. code-block:: console

   $ pw watch stm32f429i -C out2 python.lint

The ``stm32f429i`` target is built in the default build directory (``out``).
The ``python.lint`` target is built in the custom build directory (``out2``).

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>`.

----------------------------
Build-system-agnostic guides
----------------------------
This section discusses general use cases that all apply to all ``pw watch``
usage. In other words, these use cases are not affected by whether you're
using GN, Bazel, and so on.

Ignore files
------------
``pw watch`` only rebuilds when a file that is not ignored by Git changes.
Adding exclusions to a ``.gitignore`` causes ``pw 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.

Automatically reload docs
-------------------------
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.

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 :kbd:`Enter` to immediately restart a build.