cmake: explain BUILD_VERSION and KERNEL_VERSION_*

- Add examples for the latter.
- Point at each other and highlight how independent they are from each
  other.
- State their inputs and outputs in plain English.
- Fix "git describe" error message giving the wrong impression that
  everyone cares about BUILD_VERSION. Only the boot banner cares now.

Signed-off-by: Marc Herbert <marc.herbert@intel.com>

cmake/git.cmake

@@ -1,6 +1,15 @@
 # SPDX-License-Identifier: Apache-2.0
 
-# Use git if it is installed, to set BUILD_VERSION
+#.rst:
+# git.cmake
+# ---------
+# If the user didn't already define BUILD_VERSION then try to initialize
+# it with the output of "git describe". Warn but don't error if
+# everything fails and leave BUILD_VERSION undefined.
+#
+# See also: independent and more static ``KERNEL_VERSION_*`` in
+# ``version.cmake`` and ``kernel_version.h``
+
 
 # https://cmake.org/cmake/help/latest/module/FindGit.html
 find_package(Git QUIET)
@@ -15,7 +24,8 @@ if(NOT BUILD_VERSION AND GIT_FOUND)
     RESULT_VARIABLE                  return_code
   )
   if(return_code)
-    message(STATUS "git describe failed: ${stderr}; ${KERNEL_VERSION_STRING} will be used instead")
+    message(STATUS "git describe failed: ${stderr};
+   BUILD_VERSION is left undefined")
   elseif(CMAKE_VERBOSE_MAKEFILE)
     message(STATUS "git describe stderr: ${stderr}")
   endif()

cmake/version.cmake

@@ -1,5 +1,32 @@
 # SPDX-License-Identifier: Apache-2.0
 
+#.rst:
+# version.cmake
+# -------------
+#
+# Inputs:
+#
+#   ``*VERSION*`` and other constants set by
+#   maintainers in ``${ZEPHYR_BASE}/VERSION``
+#
+# Outputs with examples::
+#
+#   PROJECT_VERSION           1.14.99.07
+#   KERNEL_VERSION_STRING    "1.14.99-extraver"
+#
+#   KERNEL_VERSION_MAJOR       1
+#   KERNEL_VERSION_MINOR        14
+#   KERNEL_PATCHLEVEL             99
+#   KERNELVERSION            0x10E6307
+#   KERNEL_VERSION_NUMBER    0x10E63
+#   ZEPHYR_VERSION_CODE        69219
+#
+# Most outputs are converted to C macros, see ``version.h.in``
+#
+# See also: independent and more dynamic ``BUILD_VERSION`` in
+# ``git.cmake``.
+
+
 include(${ZEPHYR_BASE}/cmake/hex.cmake)
 file(READ ${ZEPHYR_BASE}/VERSION ver)
 

version.h.in

@@ -1,6 +1,8 @@
 #ifndef _KERNEL_VERSION_H_
 #define _KERNEL_VERSION_H_
 
+/* @templates@ values come from cmake/version.cmake */
+
 #cmakedefine ZEPHYR_VERSION_CODE @ZEPHYR_VERSION_CODE@
 #define ZEPHYR_VERSION(a,b,c) (((a) << 16) + ((b) << 8) + (c))