build: Overlay build vars expand ${ZEPHYR_<module>_MODULE_DIR}

Support referencing module directories by name in CONF_FILE,
OVERLAY_CONFIG, and DTC_OVERLAY_FILE so that projects can reference
overlay files in arbitrary modules.

Verified by passing all the following tests:
  ./scripts/twister -T tests/cmake/overlays/

Fixes #41830

Signed-off-by: Gregory Shue <[email protected]>

Author: Gregory Shue

cmake/modules/configuration_files.cmake

@@ -47,7 +47,8 @@ if(DEFINED CONF_FILE)
 
   # In order to support a `prj_<name>.conf pattern for auto inclusion of board
   # overlays, then we must first ensure only a single conf file is provided.
-  string(REPLACE " " ";" CONF_FILE_AS_LIST "${CONF_FILE}")
+  string(CONFIGURE "${CONF_FILE}" CONF_FILE_EXPANDED)
+  string(REPLACE " " ";" CONF_FILE_AS_LIST "${CONF_FILE_EXPANDED}")
   list(LENGTH CONF_FILE_AS_LIST CONF_FILE_LENGTH)
   if(${CONF_FILE_LENGTH} EQUAL 1)
     # Need the file name to look for match.

cmake/modules/dts.cmake

@@ -92,7 +92,8 @@ set(dts_files
 if(SUPPORTS_DTS)
   if(DTC_OVERLAY_FILE)
     # Convert from space-separated files into file list
-    string(REPLACE " " ";" DTC_OVERLAY_FILE_RAW_LIST "${DTC_OVERLAY_FILE}")
+    string(CONFIGURE "${DTC_OVERLAY_FILE}" DTC_OVERLAY_FILE_EXPANDED)
+    string(REPLACE " " ";" DTC_OVERLAY_FILE_RAW_LIST "${DTC_OVERLAY_FILE_EXPANDED}")
     foreach(file ${DTC_OVERLAY_FILE_RAW_LIST})
       file(TO_CMAKE_PATH "${file}" cmake_path_file)
       list(APPEND DTC_OVERLAY_FILE_AS_LIST ${cmake_path_file})

cmake/modules/kconfig.cmake

@@ -69,12 +69,14 @@ set(DOTCONFIG                  ${PROJECT_BINARY_DIR}/.config)
 set(PARSED_KCONFIG_SOURCES_TXT ${PROJECT_BINARY_DIR}/kconfig/sources.txt)
 
 if(CONF_FILE)
-string(REPLACE " " ";" CONF_FILE_AS_LIST "${CONF_FILE}")
+  string(CONFIGURE "${CONF_FILE}" CONF_FILE_EXPANDED)
+  string(REPLACE " " ";" CONF_FILE_AS_LIST "${CONF_FILE_EXPANDED}")
 endif()
 
 zephyr_get(OVERLAY_CONFIG SYSBUILD LOCAL)
 if(OVERLAY_CONFIG)
-  string(REPLACE " " ";" OVERLAY_CONFIG_AS_LIST "${OVERLAY_CONFIG}")
+  string(CONFIGURE "${OVERLAY_CONFIG}" OVERLAY_CONFIG_EXPANDED)
+  string(REPLACE " " ";" OVERLAY_CONFIG_AS_LIST "${OVERLAY_CONFIG_EXPANDED}")
 endif()
 
 if((DEFINED BOARD_REVISION) AND EXISTS ${BOARD_DIR}/${BOARD}_${BOARD_REVISION_STRING}.conf)

doc/build/dts/howtos.rst

@@ -222,7 +222,10 @@ 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 overlay files to use. If :makevar:`DTC_OVERLAY_FILE` specifies multiple
-files, they are included in that order by the C preprocessor.
+files, they are included in that order by the C preprocessor.  A file in a
+Zephyr module can be referred to by escaping the Zephyr module dir variable
+like ``\${ZEPHYR_<module>_MODULE_DIR}/<path-to>/dts.overlay``
+when setting the DTC_OVERLAY_FILE variable.
 
 You can set :makevar:`DTC_OVERLAY_FILE` to contain exactly the files you want
 to use. Here is an :ref:`example <west-building-dtc-overlay-file>` using

doc/build/kconfig/setting.rst

@@ -170,7 +170,10 @@ The application configuration can come from the sources below. By default,
 
 All configuration files will be taken from the application's configuration
 directory except for files with an absolute path that are given with the
-``CONF_FILE`` argument.
+``CONF_FILE``, ``OVERLAY_CONFIG``, and ``DTC_OVERLAY_FILE`` arguments.  For these,
+a file in a Zephyr module can be referred by escaping the Zephyr module dir
+variable like this ``\${ZEPHYR_<module>_MODULE_DIR}/<path-to>/<file>``
+when setting any of said variables in the application's :file:`CMakeLists.txt`.
 
 See :ref:`Application Configuration Directory <application-configuration-directory>`
 on how the application configuration directory is defined.

tests/cmake/overlays/var_expansions/CMakeLists.txt

@@ -0,0 +1,12 @@
+# SPDX-License-Identifier: Apache-2.0
+
+cmake_minimum_required(VERSION 3.20.0)
+
+set(ZEPHYR_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/my_module")
+set(ZEPHYR_EXTRA_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/my_extra_module")
+
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+project(overlay_var_expansions)
+
+FILE(GLOB app_sources src/*.c)
+target_sources(app PRIVATE ${app_sources})

tests/cmake/overlays/var_expansions/my_extra_module/zephyr/module.yml

@@ -0,0 +1 @@
+name:  my_extra_module_name

tests/cmake/overlays/var_expansions/my_extra_module/zephyr/my_extra_module-board.overlay

@@ -0,0 +1,9 @@
+/*
+ * Copyright (c) 2022 Legrand, Inc.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/ {
+        /* This file is intentionally empty */
+};

tests/cmake/overlays/var_expansions/my_extra_module/zephyr/my_extra_module-overlay.conf

@@ -0,0 +1 @@
+# extra-overlay-empty.conf

tests/cmake/overlays/var_expansions/my_module/zephyr/module.yml

@@ -0,0 +1 @@
+name:  my_module_name