scripts: support propagating workspace status to zephyr revision

The PR zephyrproject-rtos#39382 raised a discussion on build reproducibility and knowledge
of west projects being out of sync with the west manifest.

Similar to how `git submodules` will report the working tree dirty if
any of the submodules HEAD points to a SHA different than the one
recorded in the super project.

Based on this discussion this commit extends the Zephyr and manifest
repo (when `west` is used) revisions to include the concatenated states
of the workspace.

The workspace states are:
>  dirty: false / true
>  extra: false / true
>  off:   false / true

the final revision will become: <SHA>-<state1>-<state2>-<state3>

For example:
> zephyr:
>  path: /.../zephyr
>  revision: <SHA>-dirty-extra-off

or
> zephyr:
>  path: /.../zephyr
>  revision: <SHA>-extra

The `BUILD_OUTPUT_META_STATE_PROPAGATE` Kconfig setting is introduced
to provide user control of this behavior.

Signed-off-by: Torsten Rasmussen <[email protected]>

CMakeLists.txt

@@ -1470,6 +1470,7 @@ if(CONFIG_BUILD_OUTPUT_META)
             ${ZEPHYR_MODULES_ARG}
             ${ZEPHYR_EXTRA_MODULES_ARG}
             --meta-out ${KERNEL_META_NAME}
+            $<$<BOOL:${CONFIG_BUILD_OUTPUT_META_STATE_PROPAGATE}>:--meta-state-propagate>
   )
   list(APPEND
     post_build_byproducts

Kconfig.zephyr

@@ -523,6 +523,24 @@ config BUILD_OUTPUT_META
 	             The off state is only present if a west workspace is found.
 	  File extension is .meta
 
+config BUILD_OUTPUT_META_STATE_PROPAGATE
+	bool "Propagate module and project state"
+	depends on BUILD_OUTPUT_META
+	help
+	  Propagate to state of each module to the Zephyr revision field.
+	  If west is used the state of each west project is also propagated to
+	  the Zephyr revision field.
+	  West manifest repo revision field will also
+	  be marked with the same state as the Zephyr revision.
+	  The final revision will become: <SHA>-<state1>-<state2>-<state3>...
+	  If no states are appended to the SHA it means the build is of a clean
+	  tree.
+	  - dirty: one or more repositories are marked dirty
+	  - extra: extra Zephyr modules are manually included in the build
+	  - off:   the SHA of one or more west projects are not what the manifest
+	           defined when `west update` was run the last time (`manifest-rev`).
+	           The off state is only present if a west workspace is found.
+
 endmenu
 
 config EXPERIMENTAL

scripts/zephyr_module.py

@@ -246,7 +246,8 @@ def process_twister(module, meta):
     return out
 
 
-def process_meta(zephyr_base, west_projects, modules, extra_modules=None):
+def process_meta(zephyr_base, west_projects, modules, extra_modules=None,
+                 propagate_state=False):
     # Process zephyr_base, projects, and modules and create a dictionary
     # with meta information for each input.
     #
@@ -339,6 +340,24 @@ def git_revision(path):
     meta['workspace'].update({'dirty': workspace_dirty,
                               'extra': workspace_extra})
 
+    if propagate_state:
+        if workspace_dirty and not zephyr_dirty:
+            zephyr_revision += '-dirty'
+        if workspace_extra:
+            zephyr_revision += '-extra'
+        if workspace_off:
+            zephyr_revision += '-off'
+        zephyr_project.update({'revision': zephyr_revision})
+
+        if west_projects is not None:
+            if workspace_dirty and not manifest_dirty:
+                manifest_revision += '-dirty'
+            if workspace_extra:
+                manifest_revision += '-extra'
+            if workspace_off:
+                manifest_revision += '-off'
+            manifest_project.update({'revision': manifest_revision})
+
     return meta
 
 
@@ -447,6 +466,10 @@ def main():
                              of Zephyr modules and west projects.
                              If a module or project is also a git repository
                              the current SHA revision will also be written.""")
+    parser.add_argument('--meta-state-propagate', action='store_true',
+                        help="""Propagate state of modules and west projects
+                             to the suffix of the Zephyr SHA and if west is
+                             used, to the suffix of the manifest SHA""")
     parser.add_argument('--settings-out',
                         help="""File to write with resulting <name>:<value>
                              values to use for including in CMake""")
@@ -509,7 +532,7 @@ def main():
 
     if args.meta_out:
         meta = process_meta(args.zephyr_base, west_proj, modules,
-                            args.extra_modules)
+                            args.extra_modules, args.meta_state_propagate)
 
         with open(args.meta_out, 'w', encoding="utf-8") as fp:
             fp.write(yaml.dump(meta))