version: Add the release label interfaces

- Mark the VC key interfaces as deprecated in doxygen

Updates #5037

cpukit/include/rtems/version.h

@@ -104,6 +104,8 @@ int rtems_version_minor( void );
 int rtems_version_revision( void );
 
 /**
+ * @deprecated
+ *
  * @brief Returns the version control key for the current version of code that
  * has been built.
  *
@@ -118,6 +120,8 @@ int rtems_version_revision( void );
 const char *rtems_version_control_key( void );
 
 /**
+ * @deprecated
+ *
  * @brief Returns true, if the version control key is valid, otherwise false.
  *
  * @retval true The version control key is valid.
@@ -128,6 +132,28 @@ static inline bool rtems_version_control_key_is_valid( const char *key )
   return key[ 0 ] != '\0';
 }
 
+/**
+ * @brief Returns the revision label for the current version of code
+ * that has been built.
+ *
+ * The release label is a string of characters. Only the RTEMS project
+ * released sources can have an empty release label.
+ *
+ * Use rtems_version_release_label_is_valid() to check if the release label
+ * is valid.
+ *
+ * @return The release label.
+ */
+const char *rtems_version_release_label( void );
+
+/**
+ * @brief Returns true, if the release label is valid, otherwise false.
+ *
+ * @retval true The release label is valid.
+ * @retval false Otherwise.
+ */
+bool rtems_version_release_label_is_valid( void );
+
 /**
  * @brief Returns the board support package name.
  *

cpukit/libmisc/shell/main_rtems.c

@@ -46,8 +46,8 @@ static void kernel_summary(void) {
   printf(
     "RTEMS: %d.%d.%d",
     rtems_version_major(), rtems_version_minor(), rtems_version_revision());
-  if (rtems_version_control_key_is_valid(rtems_version_control_key())) {
-    printf(" (%s)", rtems_version_control_key());
+  if (rtems_version_release_label_is_valid()) {
+    printf(" (%s)", rtems_version_release_label());
   }
 #if RTEMS_SMP
     printf(" SMP:%d cores", rtems_scheduler_get_processor_maximum());
@@ -130,11 +130,11 @@ static int rtems_shell_main_rtems(
       tools_summary();
       opts_summary();
     } else {
-      printf("error: invalid command\n");
+      printf("error: invalid command; try `help`\n");
       return 1;
     }
   } else {
-    printf("error: invalid command\n");
+    printf("error: invalid command; try `help`\n");
     return 1;
   }
   return 0;

cpukit/sapi/src/version.c

@@ -10,15 +10,16 @@
  *   and rtems_version_revision().
  *
  * The version strings are created from the various pieces of version
- * information.  The main version number is part of the build system and is
- * stamped into <rtems/score/cpuopts.h>.  The version control key string is
- * extracted from the version control tool when the code is being built and is
- * updated if it has changed.  It is defined in "version-vc-key.h".  The key
- * may indicate there are local modification.
+ * information.  The main version number is part of the build system
+ * and is stamped into <rtems/score/cpuopts.h>. The revision label is
+ * determined by the build system and is a string. It can be used and
+ * so set when deploying the sources or the release label can be
+ * formed using the version control tool when the code is not released
+ * and being built with a version controlled repository.
  */
 
 /*
- *  Copyright (C) 2017.
+ *  Copyright (C) 2017, 2024.
  *  Chris Johns <chrisj@rtems.org>
  *
  * Redistribution and use in source and binary forms, with or without
@@ -84,3 +85,22 @@ const char *rtems_version_control_key( void )
   return "";
 #endif
 }
+
+const char *rtems_version_release_label( void )
+{
+  /*
+   * RTEMS 5 and 6 only provide the VC key. The VC key header will be
+   * moved to `version-release-label.h` after RTEMS 6
+   */
+#ifdef RTEMS_VERSION_CONTROL_KEY
+  return RTEMS_VERSION_CONTROL_KEY;
+#else
+  return "";
+#endif
+}
+
+bool rtems_version_release_label_is_valid( void )
+{
+  const char* release_label = rtems_version_release_label( );
+  return release_label[ 0 ] != '\0';
+}

wscript

@@ -1391,10 +1391,19 @@ def check_environment(conf):
 
 def load_version(ctx):
     global default_prefix
+
+    def _check_num(s):
+        try:
+            i = int(s)
+        except:
+            ctx.fatal(
+                "Invalid VERSION number: version number is not a number: " + s)
+
     cp = configparser.ConfigParser()
     version_file = "VERSION"
     version_major = None
     version_minor = None
+    version_revision = None
     version_label = None
     prefix = None
     if cp.read([version_file]):
@@ -1403,24 +1412,33 @@ def load_version(ctx):
             # The revision is <major>.<minor>[-label]
             # break is up and update the version
             if "." not in value:
-                ctx.fatal("Invalid VERSION revision: no dot")
-            vs = value.split(".", 1)
+                ctx.fatal(
+                    "Invalid VERSION revision: no number (dot) separator")
+            # version-string => major.minor[.revsion][-label]
+            vs = value.split(".", 2)
+            _check_num(vs[0])
             version_major = vs[0]
-            vs[0] = vs[1]
-            if "." in vs[0]:
-                ctx.fatal("Invalid VERSION revision: too many dots")
-            if "-" in vs[0]:
-                value = vs[0]
-                vs = value.split("-", 1)
-                version_label = vs[1]
-            version_minor = vs[0]
+            if "-" in vs[-1]:
+                ls = vs[-1].split("-", 1)
+                vs[-1] = ls[0]
+                version_label = ls[1]
+            _check_num(vs[1])
+            version_minor = vs[1]
+            if len(vs) == 3:
+                _check_num(vs[2])
+                version_revision = vs[2]
             prefix = "/opt/rtems/" + version_major
         except configparser.NoOptionError:
             pass
+    if version_label is None and version_revision is not None:
+        ctx.fatal(
+            "Invalid VERSION revision: a revision number requires a label")
     if version_major is not None:
         version["__RTEMS_MAJOR__"] = version_major
     if version_minor is not None:
         version["__RTEMS_MINOR__"] = version_minor
+    if version_revision is not None:
+        version["__RTEMS_REVISION__"] = version_revision
     if version_label is not None:
         version["RTEMS_RELEASE_VERSION_LABEL"] = version_label
     # Checking minor insures major and minor are valid
@@ -1432,6 +1450,8 @@ def load_version(ctx):
 def configure_version(conf):
     version_label = load_version(conf)
     v_str = version["__RTEMS_MAJOR__"] + "." + version["__RTEMS_MINOR__"]
+    if int(version["__RTEMS_REVISION__"]) != 0 and version_label != "":
+        v_str += "." + version["__RTEMS_REVISION__"]
     if version_label != "":
         v_str += "." + version_label
     conf.msg("Configure RTEMS version", v_str, color="YELLOW")