doc: add more cross-references/examples for DT overlays

Device tree overlays are a bit of a stumbling block. Try to add more
cross-references and examples for how to use them to the application
development doc and the west build page.

Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>

doc/application/index.rst

@@ -279,7 +279,8 @@ should know about.
 * :makevar:`DTC_OVERLAY_FILE`: Indicates the name of one or more Device Tree
   overlay files. Multiple filenames can be separated with either spaces or
   semicolons. Each file includes Device Tree values that override the default
-  DT values.
+  DT values. See :ref:`application_dt` below for details on device tree
+  overlays, and :ref:`device-tree` for an overview on devicetree and Zephyr.
 
 * :makevar:`ZEPHYR_MODULES`: A CMake list containing absolute paths of
   additional directories with source code, Kconfig, etc. that should be used in
@@ -1492,15 +1493,17 @@ docstrings at the top of ``scripts/kconfig/menuconfig.py`` and
 Device Tree Overlays
 ====================
 
-As described in :ref:`device-tree`, Zephyr uses Device Tree to
+As described in :ref:`device-tree`, Zephyr uses Device Tree to describe the
-describe the hardware it runs on. This section describes how you can
+hardware it runs on. This section describes how you can modify an application
-modify an application build's device tree using overlay files. For additional
+build's device tree using overlay files. For additional information regarding
-information regarding the relationship between Device Tree and Kconfig see
+the relationship between Device Tree and Kconfig see :ref:`dt_vs_kconfig`. For
-:ref:`dt_vs_kconfig`. In some cases the information contained in Device Tree
+an example of how to use custom overlays with ``west build``, see
-files is closely connected to the software and might need to be modified
+:ref:`west-building-cmake-args`.
-using the overlay file concept. This can be relevant for many of the different
+
-Device Tree nodes, but is particularly useful for :ref:`certain types
+In some cases the information contained in Device Tree files is closely
-of nodes <dt-alias-chosen>`.
+connected to the software and might need to be modified using the overlay file
+concept. This can be relevant for many of the different Device Tree nodes, but
+is particularly useful for :ref:`certain types of nodes <dt-alias-chosen>`.
 
 Overlay files, which customarily have the :file:`.overlay` extension,
 contain device tree fragments which add to or modify the device tree

doc/guides/west/build-flash-debug.rst

@@ -76,6 +76,13 @@ Examples
 
 Here are some ``west build`` usage examples, grouped by area.
 
+Forcing CMake to Run Again
+--------------------------
+
+To force a CMake re-run, use the ``--cmake`` (or ``--c``) option::
+
+  west build -c
+
 Setting a Default Board
 -----------------------
 
@@ -110,11 +117,8 @@ With the above, running ``west build -b reel_board samples/hello_world`` will
 use build directory :file:`build/reel_board/hello_world`.  See
 :ref:`west-building-config` for more details on this option.
 
-Controlling the Build System
+Setting the Build System Target
-----------------------------
+-------------------------------
-
-There are several ways to control the build system generated and used by ``west
-build``.
 
 To specify the build system target to run, use ``--target`` (or ``-t``).
 
@@ -133,10 +137,16 @@ all the files in the build directory::
 
   west build -t pristine
 
-To have ``west build`` run the ``pristine`` target before re-running CMake to
+Pristine Builds
-generate a build system, use the ``--pristine`` (or ``-p``) option. For
+---------------
-example, to switch board and application (which requires a pristine build
+
-directory) in one command::
+A *pristine* build directory is essentially a new build directory. All
+byproducts from previous builds have been removed.
+
+To have ``west build`` make the build directory pristine before re-running
+CMake to generate a build system, use the ``--pristine`` (or ``-p``)
+option. For example, to switch board and application (which requires a pristine
+build directory) in one command::
 
   west build -b qemu_x86 samples/philosophers
   west build -p -b reel_board samples/hello_world
@@ -151,22 +161,28 @@ To let west decide for you if a pristine build is needed, use ``-p auto``::
    permanent.
 
 .. _west-building-generator:
+.. _west-building-cmake-args:
 
-To add additional arguments to the CMake invocation performed by ``west
+Additional CMake Arguments
+--------------------------
+
+To pass additional arguments to the CMake invocation performed by ``west
 build``, pass them after a ``--`` at the end of the command line.
 
+.. important::
+
+   Passing additional CMake arguments like this forces ``west build`` to re-run
+   CMake, even if a build system has already been generated.
+
+   After using ``--`` once to generate the build directory, use ``west build -d
+   <build-dir>`` on subsequent runs to do incremental builds.
+
 For example, to use the Unix Makefiles CMake generator instead of Ninja (which
 ``west build`` uses by default), run::
 
   west build -b reel_board -- -G'Unix Makefiles'
 
-.. note::
+To use Unix Makefiles and set `CMAKE_VERBOSE_MAKEFILE`_ to ``ON``::
-
-   Passing additional CMake arguments like this forces ``west build`` to re-run
-   CMake, even if a build system has already been generated.
-
-As another example, to use Unix Makefiles and enable the
-`CMAKE_VERBOSE_MAKEFILE`_ option::
 
   west build -b reel_board -- -G'Unix Makefiles' -DCMAKE_VERBOSE_MAKEFILE=ON
 
@@ -174,15 +190,16 @@ Notice how the ``--`` only appears once, even though multiple CMake arguments
 are given. All command-line arguments to ``west build`` after a ``--`` are
 passed to CMake.
 
-As a final example, to merge the :file:`file.conf` Kconfig fragment into your
+To set :ref:`DTC_OVERLAY_FILE <application_dt>` to :file:`enable-modem.overlay`,
-build's :file:`.config`::
+using that file as a :ref:`device tree overlay <device-tree>`::
+
+  west build -b reel_board -- -DDTC_OVERLAY_FILE=enable-modem.overlay
+
+To merge the :file:`file.conf` Kconfig fragment into your build's
+:file:`.config`::
 
   west build -- -DOVERLAY_CONFIG=file.conf
 
-To force a CMake re-run, use the ``--cmake`` (or ``--c``) option::
-
-  west build -c
-
 .. _west-building-config:
 
 Configuration Options