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.

Fixes #41830

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

Author: Gregory Shue

cmake/app/boilerplate.cmake

@@ -444,7 +444,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/dts.cmake

@@ -69,7 +69,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/kconfig.cmake

@@ -52,11 +52,13 @@ 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()
 
 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/application/index.rst

@@ -478,7 +478,10 @@ Application Configuration Directory
 Zephyr will use configuration files from the application's configuration
 directory except for files with an absolute path provided by the arguments
 described earlier, for example ``CONF_FILE``, ``OVERLAY_CONFIG``, and
-``DTC_OVERLAY_FILE``.
+``DTC_OVERLAY_FILE``.  A file in a Zephyr module can be referred by
+escaping the Zephyr module dir variable like this
+``\${ZEPHYR_<modulename>_MODULE_DIR}/<path-to>/<file>``
+when setting any of said variables.
 
 The application configuration directory is defined by the
 ``APPLICATION_CONFIG_DIR`` variable.

doc/guides/dts/howtos.rst

@@ -202,7 +202,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_<modulename>_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

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