doc: dts: clear up DTC_OVERLAY_FILE

Make it clearer that you can set it explicitly or the build system
will try to set it for you, and try to make it clearer what the build
system is doing when it tries to set it on your behalf.

Signed-off-by: Martí Bolívar <[email protected]>

Author: mbolivar-nordic

doc/guides/dts/howtos.rst

@@ -201,26 +201,30 @@ Set devicetree overlays
 
 Devicetree overlays are explained in :ref:`devicetree-intro`. The CMake
 variable :makevar:`DTC_OVERLAY_FILE` contains a space- or semicolon-separated
-list of overlays. If :makevar:`DTC_OVERLAY_FILE` specifies multiple files, they
-are included in that order by the C preprocessor.
-
-Here are some ways to set it:
-
-1. on the cmake build command line
-   (``-DDTC_OVERLAY_FILE="file1.overlay;file2.overlay"``)
-#. with the CMake ``set()`` command in the application ``CMakeLists.txt``,
-   before including zephyr's :file:`boilerplate.cmake` file
-#. create a ``boards/<BOARD>_<revision>.overlay`` file in the application
-   folder for the current board revision. This requires that the board supports
-   multiple revisions, see :ref:`porting_board_revisions`.
-   The ``boards/<BOARD>_<revision>.overlay`` file will be merged with
-   ``boards/<BOARD>.overlay`` if this file also exists.
-#. create a ``boards/<BOARD>.overlay`` file in the application
-   folder, for the current board
-#. create a ``<BOARD>.overlay`` file in the application folder
-#. create an ``app.overlay`` file in the application folder
-
-Here is an example :ref:`using west build <west-building-dtc-overlay-file>`.
+list of overlay files to use. If :makevar:`DTC_OVERLAY_FILE` specifies multiple
+files, they are included in that order by the C preprocessor.
+
+You can set :makevar:`DTC_OVERLAY_FILE` to contain exactly the files you want
+to use. Here is an example :ref:`using west build
+<west-building-dtc-overlay-file>`.
+
+If you don't set :makevar:`DTC_OVERLAY_FILE`, the build system will follow
+these steps, looking for files in your application source directory to use
+as devicetree overlays:
+
+#. If the file :file:`boards/<BOARD>.overlay` exists, it will be used.
+#. If the current board has :ref:`multiple revisions <porting_board_revisions>`
+   and :file:`boards/<BOARD>_<revision>.overlay` exists, it will be used.
+   This file will be used in addition to :file:`boards/<BOARD>.overlay`
+   if both exist.
+#. If one or more files have been found in the previous steps, the build system
+   stops looking and just uses those files.
+#. Otherwise, if :file:`<BOARD>.overlay` exists, it will be used, and the build
+   system will stop looking for more files.
+#. Otherwise, if :file:`app.overlay` exists, it will be used.
+
+Using :ref:`shields` will also add devicetree overlay files.
+
 However you set the value, it is saved in the CMake cache between builds.
 
 The :ref:`build system <build_overview>` prints all the devicetree overlays it