cmake: ensure consistent behavior between x_ROOT settings

Fixes: #23825

Today, BOARD, SOC, ARCH, DTS, KCONFIG, and TOOLCHAIN_ROOT can be
specified by users or through other CMake files.

It is not clear if relative paths are permitted and/or from where a
relative path is constructed.

Inside CMake, it is very easy to specify `${ZEPHYR_BASE}`,
`${CMAKE_CURRENT_SOURCE_DIR}`, or similar, thus there is no reason to
use relative path inside CMake, as it easy can lead to discussion on
relative to what.

For users manually invoking CMake using, `cmake ... <app-dir>` it is
nice to have to possibility to specify a relative path.
For this purpose, relative path are considered relative to the
`APPLICATION_SOURCE_DIR`.

This commit updates:
- BOARD_ROOT
- SOC_ROOT
- ARCH_ROOT
- DTS_ROOT
- KCONFIG_ROOT
- TOOLCHAIN_ROOT

to allow paths relative to `APPLICATION_SOURCE_DIR` when specified with
`-D<type>_ROOT=<relative-path>`

Signed-off-by: Torsten Rasmussen <Torsten.Rasmussen@nordicsemi.no>

cmake/app/boilerplate.cmake

@@ -305,14 +305,17 @@ set(CACHED_SHIELD ${SHIELD} CACHE STRING "Selected shield")
 
 # 'BOARD_ROOT' is a prioritized list of directories where boards may
 # be found. It always includes ${ZEPHYR_BASE} at the lowest priority.
+zephyr_file(APPLICATION_ROOT BOARD_ROOT)
 list(APPEND BOARD_ROOT ${ZEPHYR_BASE})
 
 # 'SOC_ROOT' is a prioritized list of directories where socs may be
 # found. It always includes ${ZEPHYR_BASE}/soc at the lowest priority.
+zephyr_file(APPLICATION_ROOT SOC_ROOT)
 list(APPEND SOC_ROOT ${ZEPHYR_BASE})
 
 # 'ARCH_ROOT' is a prioritized list of directories where archs may be
 # found. It always includes ${ZEPHYR_BASE} at the lowest priority.
+zephyr_file(APPLICATION_ROOT ARCH_ROOT)
 list(APPEND ARCH_ROOT ${ZEPHYR_BASE})
 
 if(DEFINED SHIELD)

cmake/dts.cmake

@@ -35,6 +35,8 @@ if(DEFINED DTS_COMMON_OVERLAYS)
   message(FATAL_ERROR "DTS_COMMON_OVERLAYS is no longer supported. Use DTC_OVERLAY_FILE instead.")
 endif()
 
+zephyr_file(APPLICATION_ROOT DTS_ROOT)
+
 # 'DTS_ROOT' is a list of directories where a directory tree with DT
 # files may be found. It always includes the application directory,
 # the board directory, and ${ZEPHYR_BASE}.

cmake/generic_toolchain.cmake

@@ -9,6 +9,7 @@ if(NOT TOOLCHAIN_ROOT)
     set(TOOLCHAIN_ROOT ${ZEPHYR_BASE})
   endif()
 endif()
+zephyr_file(APPLICATION_ROOT TOOLCHAIN_ROOT)
 
 # Don't inherit compiler flags from the environment
 foreach(var CFLAGS CXXFLAGS CPPFLAGS)
@@ -47,7 +48,7 @@ if("${ZEPHYR_TOOLCHAIN_VARIANT}" STREQUAL "zephyr")
   set(TOOLCHAIN_HOME ${HOST_TOOLS_HOME})
 endif()
 
-set(TOOLCHAIN_ROOT ${TOOLCHAIN_ROOT} CACHE STRING "Zephyr toolchain root")
+set(TOOLCHAIN_ROOT ${TOOLCHAIN_ROOT} CACHE STRING "Zephyr toolchain root" FORCE)
 assert(TOOLCHAIN_ROOT "Zephyr toolchain root path invalid: please set the TOOLCHAIN_ROOT-variable")
 
 # Set cached ZEPHYR_TOOLCHAIN_VARIANT.

cmake/kconfig.cmake

@@ -22,6 +22,7 @@ foreach(root ${SOC_ROOT})
 endforeach()
 
 if(KCONFIG_ROOT)
+  zephyr_file(APPLICATION_ROOT KCONFIG_ROOT)
   # KCONFIG_ROOT has either been specified as a CMake variable or is
   # already in the CMakeCache.txt. This has precedence.
 elseif(EXISTS   ${APPLICATION_SOURCE_DIR}/Kconfig)

doc/application/index.rst

@@ -673,6 +673,12 @@ You can also define the ``BOARD_ROOT`` 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_ROOT`` in a CMakeLists.txt, then an absolute path must
+   be provided, for example ``list(APPEND BOARD_ROOT ${CMAKE_CURRENT_SOURCE_DIR}/<extra-board-root>``.
+   When using ``-DBOARD_ROOT=<board-root>`` both absolute and relative paths can
+   be used. Relative paths are treated relatively to the application directory.
 
 SOC Definitions
 ===============
@@ -750,6 +756,13 @@ Or you can define the ``SOC_ROOT`` 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 ``SOC_ROOT`` in a CMakeLists.txt, then an absolute path must
+   be provided, for example ``list(APPEND SOC_ROOT ${CMAKE_CURRENT_SOURCE_DIR}/<extra-soc-root>``.
+   When using ``-DSOC_ROOT=<soc-root>`` both absolute and relative paths can be
+   used. Relative paths are treated relatively to the application directory.
+
 .. _dts_root:
 
 Devicetree Definitions
@@ -783,6 +796,13 @@ You can also define the 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 ``DTS_ROOT`` in a CMakeLists.txt, then an absolute path must
+   be provided, for example ``list(APPEND DTS_ROOT ${CMAKE_CURRENT_SOURCE_DIR}/<extra-dts-root>``.
+   When using ``-DDTS_ROOT=<dts-root>`` both absolute and relative paths can be
+   used. Relative paths are treated relatively to the application directory.
+
 Devicetree source are passed through the C preprocessor, so you can
 include files that can be located in a ``DTS_ROOT`` directory.  By
 convention devicetree include files have a ``.dtsi`` extension.