michaelh/zephyr
1
0
Fork 0
Code Releases Activity

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

Browse source 
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>
This commit is contained in:
Marti Bolivar 2019-10-04 12:23:55 -07:00 • committed by Carles Cufí
commit 2fa0c4874a
2 changed files with 53 additions and 33 deletions
Download patch file Download diff file Expand all files Collapse all files

23
doc/application/index.rst
View file

@ -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
describe the hardware it runs on. This section describes how you can
modify an application build's device tree using overlay files. For additional
information regarding the relationship between Device Tree and Kconfig see
:ref:`dt_vs_kconfig`. In some cases the information contained in Device Tree
files is closely 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>`.
As described in :ref:`device-tree`, Zephyr uses Device Tree to describe the
hardware it runs on. This section describes how you can modify an application
build's device tree using overlay files. For additional information regarding
the relationship between Device Tree and Kconfig see :ref:`dt_vs_kconfig`. For
an example of how to use custom overlays with ``west build``, see
:ref:`west-building-cmake-args`.
In some cases the information contained in Device Tree files is closely
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

63
doc/guides/west/build-flash-debug.rst
View file

@ -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
----------------------------
There are several ways to control the build system generated and used by ``west
build``.
Setting the Build System Target
-------------------------------
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
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::
Pristine Builds
---------------
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::
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::
To use Unix Makefiles and set `CMAKE_VERBOSE_MAKEFILE`_ to ``ON``::
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
build's :file:`.config`::
To set :ref:`DTC_OVERLAY_FILE <application_dt>` to :file:`enable-modem.overlay`,
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