michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: dts: clear up DTC_OVERLAY_FILE

Browse source 
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 <marti.bolivar@nordicsemi.no>
This commit is contained in:
Martí Bolívar 2021-11-12 14:59:12 -08:00 • committed by Christopher Friedt
commit 46de74b8de
1 changed files with 21 additions and 17 deletions
Download patch file Download diff file Expand all files Collapse all files

38
doc/guides/dts/howtos.rst
View file

@ -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.
list of overlay files to use. 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:
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>`.
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
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.
Here is an example :ref:`using west build <west-building-dtc-overlay-file>`.
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