cmake: introduce build_info function

The build_info function provides a generic and stable way of dumping
build information to the <build>/build_info.yml file.

The build info file is in YAML format and the keys in the file are
intended to be stable, as to allow external tools to retrieve
information regarding the build.

The main differences to the CMakeCache.txt are:
- Settings in the CMakeCache.txt are user controlled, whereas the
  information in the build info file is intended to be those values
  which are used by the build system regardless if those are specified
  by the developer or picked up automatically.
- Internal build system variables are not present in the CMake cache
  and should not be, because their values are calculated when CMake
  runs.

This also has the benefits of decoupling CMake variable names from
build info keys. Several CMake variables has internal build system
names, and the build system is free to rename those at its own
discretion.

Having dedicated key names ensures a stable API that external tools can
rely upon.

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

cmake/modules/extensions.cmake

@@ -3657,6 +3657,67 @@ function(topological_sort)
   set(${TS_RESULT} "${sorted_targets}" PARENT_SCOPE)
 endfunction()
 
+# Usage:
+#   build_info(<tag>... VALUE <value>...)
+#
+# This function populates updates the build_info.yml info file with exchangable build information
+# related to the current build.
+#
+# Example:
+#   build_info(devicetree files VALUE file1.dts file2.dts file3.dts)
+# Will update the 'devicetree files' key in the build info yaml with the list
+# of files, file1.dts file2.dts file3.dts.
+#
+#   build_info(vendor-specific foo VALUE bar)
+# Will place the vendor specific key 'foo' with value 'bar' in the vendor specific section
+# of the build info file.
+#
+# <tag>...: One of the pre-defined valid CMake keys supported by build info or vendor-specific.
+#           See 'scripts/schemas/build-schema.yml' CMake section for valid tags.
+# VALUE <value>... : value(s) to place in the build_info.yml file.
+function(build_info)
+  set(arg_list ${ARGV})
+  list(FIND arg_list VALUE index)
+  if(index EQUAL -1)
+    message(FATAL_ERROR "${CMAKE_CURRENT_FUNCTION}(...) missing a required argument: VALUE")
+  endif()
+
+  yaml_context(EXISTS NAME build_info result)
+  if(NOT result)
+    yaml_load(FILE ${ZEPHYR_BASE}/scripts/schemas/build-schema.yml NAME build_info_schema)
+    if(EXISTS ${CMAKE_BINARY_DIR}/build_info.yml)
+      yaml_load(FILE ${CMAKE_BINARY_DIR}/build_info.yml NAME build_info)
+    else()
+      yaml_create(FILE ${CMAKE_BINARY_DIR}/build_info.yml NAME build_info)
+    endif()
+    yaml_set(NAME build_info KEY version VALUE "0.1.0")
+  endif()
+
+  list(SUBLIST arg_list 0 ${index} keys)
+  list(SUBLIST arg_list ${index} -1 values)
+  list(POP_FRONT values)
+
+  if(ARGV0 STREQUAL "vendor-specific")
+    set(type VALUE)
+  else()
+    set(schema_check ${keys})
+    list(TRANSFORM schema_check PREPEND "mapping;")
+    yaml_get(check NAME build_info_schema KEY mapping cmake ${schema_check})
+    if(check MATCHES ".*-NOTFOUND")
+      message(FATAL_ERROR "${CMAKE_CURRENT_FUNCTION}(...) called with invalid tag: ${keys}")
+    endif()
+
+    yaml_get(type NAME build_info_schema KEY mapping cmake ${schema_check} type)
+    if(type MATCHES "seq|sequence")
+      set(type LIST)
+    else()
+      set(type VALUE)
+    endif()
+  endif()
+
+  yaml_set(NAME build_info KEY cmake ${keys} ${type} "${values}")
+endfunction()
+
 ########################################################
 # 4. Devicetree extensions
 ########################################################
@@ -5794,4 +5855,13 @@ if(CMAKE_SCRIPT_MODE_FILE)
   function(zephyr_set variable)
     # This silence the error: zephyr_set(...  SCOPE <scope>) doesn't exists.
   endfunction()
+
+  # Build info creates a custom target for handling of build info.
+  # build_info is not needed in script mode but still called by Zephyr CMake
+  # modules. Therefore disable build_info(...) in when including
+  # extensions.cmake in script mode.
+  function(build_info)
+    # This silence the error: 'YAML context 'build_info' does not exist.'
+    #                         'Remember to create a YAML context'
+  endfunction()
 endif()

cmake/modules/unittest.cmake

@@ -4,6 +4,7 @@ cmake_minimum_required(VERSION 3.20.0)
 
 include(extensions)
 include(west)
+include(yaml)
 include(root)
 include(zephyr_module)
 include(boards)

scripts/schemas/build-schema.yml

@@ -0,0 +1,106 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright (c) 2024, Nordic Semiconductor ASA
+
+# A pykwalify schema for basic validation of the Zephyr build info YAML file.
+
+type: map
+mapping:
+  version:
+    required: true
+    type: str
+  cmake:
+    type: map
+    mapping:
+      application:
+        type: map
+        mapping:
+          source-dir:
+            type: str
+          configuration-dir:
+            type: str
+      board:
+        type: map
+        mapping:
+          name:
+            required: true
+            type: str
+          qualifiers:
+            type: str
+          revision:
+            type: str
+          path:
+            type: seq
+            sequence:
+              - type: str
+      devicetree:
+        type: map
+        mapping:
+          files:
+            type: seq
+            sequence:
+              - type: str
+          user-files:
+            type: seq
+            sequence:
+              - type: str
+          extra-user-files:
+            type: seq
+            sequence:
+              - type: str
+          include-dirs:
+            type: seq
+            sequence:
+              - type: str
+          bindings-dirs:
+            type: seq
+            sequence:
+              - type: str
+      kconfig:
+        type: map
+        mapping:
+          files:
+            type: seq
+            sequence:
+              - type: str
+          user-files:
+            type: seq
+            sequence:
+              - type: str
+          extra-user-files:
+            type: seq
+            sequence:
+              - type: str
+      sysbuild:
+        type: bool
+      toolchain:
+        type: map
+        mapping:
+          name:
+            type: str
+          version:
+            type: str
+          path:
+            type: str
+      zephyr:
+        type: map
+        mapping:
+          zephyr-base:
+            type: str
+          version:
+            type: str
+      vendor-specific:
+        type: map
+        mapping:
+          regex;(.*):
+            type: map
+            mapping:
+              regex;(.*):
+                type: str
+  west:
+    type: map
+    mapping:
+      command:
+        type: str
+      topdir:
+        type: str