doc: dts: add note about BOARD_EXTENSION_DIRS

This adds a note about BOARD_EXTENSION_DIRS to the documentation on how to set devicetree overlays. Signed-off-by: Jelle De Vleeschouwer <[email protected]>
zephyrproject-rtos · Jan 3, 2025 · b0899dc · b0899dc
1 parent 99044ca
commit b0899dc
Showing 1 changed file with 12 additions and 0 deletions.
diff --git a/doc/build/dts/howtos.rst b/doc/build/dts/howtos.rst
@@ -276,6 +276,18 @@ finds in the configuration phase, like this:
 
    -- Found devicetree overlay: .../some/file.overlay
 
+Additional directories containing devicetree overlay files can also be added
+by appending to the ``BOARD_EXTENSION_DIRS`` CMake variable in the application
+:file:`CMakeLists.txt` file. Make sure to do so **before** pulling in the
+Zephyr boilerplate with ``find_package(Zephyr ...)``.
+
+.. note::
+
+   When specifying ``BOARD_EXTENSION_DIRS`` in a CMakeLists.txt, then an absolute path must
+   be provided, for example ``list(APPEND BOARD_EXTENSION_DIRS ${CMAKE_CURRENT_SOURCE_DIR}/<extension-dir>``.
+   When using ``-DBOARD_EXTENSION_DIRS=<extension-dir>`` both absolute and relative paths can be
+   used. Relative paths are treated relatively to the application directory.
+
 .. _use-dt-overlays:
 
 Use devicetree overlays