[PATCH v3] version: add a module to get GRUB version

[Flavio Suligoi]

Sometimes, writing a custom grub.cfg configuration file, especially with
embedded systems, it is indispensable to know the version of the running GRUB.
This is essential for every automatic sw update procedure.

The easier way to know the GRUB version is by dedicated environment variables.
In this way any scripts in grub.cfg file can use it directly.

The classic GRUB version "major.minor" is now extended adding two additional
items, called "git" and "oem", creating the following composed version string:

                      major.minor[.git][-oem]

  - major : the major version (mandatory and automatically added)
  - minor : the minor version (mandatory and automatically added)
  - git   : the GIT SHA-1 hash of the current commit in the GRUB repository
            (optional)
  - oem   : a custom number/string (max 256 chars) for special uses

For example a full version string could be: 2.05.c543d67-1.0.0

The above version items are readable by some dedicated environment variables:

  - grub_ver            : the full version (always set)
  - grub_ver_major      : the major version (always set)
  - grub_ver_minor      : the minor version (always set)
  - grub_ver_git_commit : the SHA-1 hash of the current GIT commit (optional)
  - grub_ver_oem        : the custom OEM number/string (optional)

The four version items are managed using the new file "VERSION".
In this file it is possible:

- change the value of each of the four version items
- comment/uncomment the two new items "git" and "oem"

Note: the two new items ("git" and "oem") can be enabled/disabled independently.

Signed-off-by: Flavio Suligoi <address@hidden>
Reviewed-by: Paul Menzel <address@hidden>
Reviewed-by: Daniel Kiper <address@hidden>
---

Changes in v3: patch fully revisited:
               - remove "version" command
               - add environment variables for version(s)
               - add "VERSION" file for fersion number/string management
Changes in v2: cosmetic changes
Changes in v1: cosmetic changes

 VERSION                 | 61 +++++++++++++++++++++++++++++++++++++++++++++
 config.h.in             |  9 +++++++
 configure.ac            | 29 +++++++++++++++++++++-
 docs/grub-dev.texi      | 49 ++++++++++++++++++++++++++++++++++++
 docs/grub.texi          | 66 +++++++++++++++++++++++++++++++++++++++++++++++++
 grub-core/normal/main.c | 30 ++++++++++++++++++++++
 6 files changed, 243 insertions(+), 1 deletion(-)
 create mode 100644 VERSION

diff --git a/VERSION b/VERSION
new file mode 100644
index 0000000..30a2a9f
--- /dev/null
+++ b/VERSION
@@ -0,0 +1,61 @@
+# VERSION - GRUB Version
+#
+# GRUB  --  GRand Unified Bootloader
+#
+# Copyright (C) 2020 Free Software Foundation, Inc.
+#
+# Copying and distribution of this file, with or without modification,
+# are permitted in any medium without royalty provided the copyright
+# notice and this notice are preserved.  This file is offered as-is,
+# without warranty of any kind.
+#
+#
+# This file contains the GRUB version, composed of four elements:
+#
+#   MAJOR.MINOR.GIT_COMMIT.OEM
+#
+# - MAJOR is the version major number (mandatory and automatically added)
+# - MINOR is the version minor number (mandatory and automatically added)
+# - GIT_COMMIT is the hash of the current git commit (optional)
+# - OEM is the custom OEM version (optional)
+#
+#
+# How to use the two optional version elements (GIT_COMMIT and OEM)
+#
+# The standard version is always automatically added with "./configure".
+#
+# The GIT_COMMIT version number can be added simply uncommenting
+# the macro "GIT_COMMIT_ENABLE" in this file, i.e.:
+#
+#                              MAJOR 2
+#                              MINOR 05
+#                              GIT_COMMIT_ENABLE
+#                              # OEM 1.0.0
+#
+# The OEM version number/string (256 chars max) can be added uncommenting
+# the macro "OEM", followed by the OEM string/number custom version, i.e:
+#
+#                              MAJOR 2
+#                              MINOR 05
+#                              # GIT_COMMIT_ENABLE
+#                              OEM 1.0.0
+#
+#
+#
+# NOTE: the GIT_COMMIT version and the OEM version are indipendent and can be
+#       also enabled simultaneously.
+#
+# IMPORTANT: don't insert spaces inside any version number/string.
+# IMPORTANT: run again the commands:
+#
+#              ./bootstrap
+#              ./configure
+#              ./autogen.sh
+#
+#            after changing also only one of the version elements.
+#
+
+MAJOR 2
+MINOR 05
+# GIT_COMMIT_ENABLE
+# OEM 1.0.0
diff --git a/config.h.in b/config.h.in
index 9e8f991..15c1947 100644
--- a/config.h.in
+++ b/config.h.in
@@ -52,6 +52,15 @@
 #define PACKAGE_STRING "@PACKAGE_STRING@"
 /* Define to the version of this package. */
 #define PACKAGE_VERSION "@PACKAGE_VERSION@"
+/* Define the major version of this package. */
+#define PACKAGE_VERSION_MAJOR "@PACKAGE_VERSION_MAJOR@"
+/* Define the minor version of this package. */
+#define PACKAGE_VERSION_MINOR "@PACKAGE_VERSION_MINOR@"
+/* Define the GIT version of this package. */
+#define PACKAGE_VERSION_GIT_COMMIT "@PACKAGE_VERSION_GIT_COMMIT@"
+/* Define the custom OEM version of this package. */
+#define PACKAGE_VERSION_OEM "@PACKAGE_VERSION_OEM@"
+
 /* Define to the full name of this package. */
 #define PACKAGE_NAME "@PACKAGE_NAME@"
 /* Define to the address where bug reports for this package should be sent. */
diff --git a/configure.ac b/configure.ac
index 88c0adb..3bb85b5 100644
--- a/configure.ac
+++ b/configure.ac
@@ -31,7 +31,34 @@ dnl (such as BUILD_CC, BUILD_CFLAGS, etc.) for the build 
type and variables
 dnl with the prefix "TARGET_" (such as TARGET_CC, TARGET_CFLAGS, etc.) are
 dnl used for the target type. See INSTALL for full list of variables.
 
-AC_INIT([GRUB],[2.05],[address@hidden])
+# Create default version string as: major.minor (see VERSION file)
+m4_define([version_major],
+  m4_esyscmd([grep -o '^[^#]*' VERSION | grep MAJOR | tr -s [:space:] | cut -d 
' ' -f2 | tr -d '\n']))
+m4_define([version_minor],
+  m4_esyscmd([grep -o '^[^#]*' VERSION | grep MINOR | tr -s [:space:] | cut -d 
' ' -f2 | tr -d '\n']))
+m4_define([version_full], [version_major.version_minor])
+
+# Add GIT version, if required (see VERSION file)
+m4_define([version_git_commit_enable],
+  m4_esyscmd([grep -o '^[^#]*' VERSION | grep GIT_COMMIT_ENABLE | tr -d '\n']))
+m4_define([version_git_commit_hash], m4_esyscmd([git log -n1 
--format=format:"%h"]))
+m4_ifnblank(version_git_commit_enable,
+  [m4_append([version_full], [version_git_commit_hash], [.])], )
+
+# Add custom OEM version, if required (see VERSION file)
+m4_define([version_oem],
+  m4_esyscmd([grep -o '^[^#]*' VERSION | grep OEM | tr -s [:space:] | cut -d ' 
' -f2 | tr -d '\n']))
+m4_ifnblank(version_oem,
+  [m4_append([version_full], [version_oem], [-])], )
+
+AC_INIT([GRUB],[version_full],[address@hidden])
+
+# Set shell variables for single versions (major, minor, GIT commit, OEM)
+AC_SUBST([PACKAGE_VERSION_MAJOR], ["version_major"])
+AC_SUBST([PACKAGE_VERSION_MINOR], ["version_minor"])
+AS_IF([test "version_git_commit_enable" = "GIT_COMMIT_ENABLE"],
+  [AC_SUBST([PACKAGE_VERSION_GIT_COMMIT], ["version_git_commit_hash"])], [])
+AC_SUBST([PACKAGE_VERSION_OEM], ["version_oem"])
 
 AC_CONFIG_AUX_DIR([build-aux])
 
diff --git a/docs/grub-dev.texi b/docs/grub-dev.texi
index 24d17b8..9b6e0d2 100644
--- a/docs/grub-dev.texi
+++ b/docs/grub-dev.texi
@@ -355,6 +355,7 @@ anymore.
 * Getting started::
 * Typical Developer Experience::
 * When you are approved for write access to project's files::
+* Version::
 @end menu
 
 @node Getting started
@@ -482,6 +483,54 @@ If your intention is to just get started, please do not 
submit a inclusion
 request. Instead, please subscribe to the mailing list, and communicate first
 (e.g. sending a patch, asking a question, commenting on another message...).
 
+@node Version
+@section Version
+
+The version of the GRUB source, in its complete form, is composed of four
+parameters:
+@itemize @bullet
+@item
+@samp{major}: the major version number (mandatory and automatically added)
+@item
+@samp{minor}: the minor version number (mandatory and automatically added)
+@item
+@samp{git}: the GIT current commit SHA-1 hash number (optional)
+@item
+@samp{oem}: the OEM custom number/string (optional)
+@end itemize
+
+The above four parameters are assembled as:
+
+@samp{major.minor[.git][-oem]}
+
+This version is exposed in the main menu and also as the following single
+environment variables (see the main GRUB user manual for details):
+@itemize @bullet
+@item
+@samp{grub_ver}: the full complete GRUB version
+@item
+@samp{grub_ver_major}: the major version number (mandatory and automatically 
added)
+@item
+@samp{grub_ver_minor}: the minor version number (mandatory and automatically 
added)
+@item
+@samp{grub_ver_git_commit}: the GIT current commit SHA-1 hash number (optional)
+@item
+@samp{grub_ver_oem}: the OEM custom number/string (optional)
+@end itemize
+
+To enable the two optional version items (@samp{git} and @samp{oem}), see the
+file @file{VERSION} in the GRUB source code.
+
+In most cases, the default version configuration @samp{major.minor} is
+sufficient.
+The other two optional versions, expecially the @samp{oem}, can be useful
+expecially in embedded systems, where GRUB can be heavily customized and an
+automatic update tool is used (i.e. same OTA update systems. etc.). In these
+cases, for example, the main version (@samp{major.minor} remains unchanged, but
+the @samp{oem} version can evolve in the time (bugfixex, new features added,
+...). Reading the @samp{oem} version, the automatic update tool can decide if
+the GRUB binary updating is necessary.
+
 @node Updating External Code
 @chapter Updating external code
 
diff --git a/docs/grub.texi b/docs/grub.texi
index d6408d2..e95cbba 100644
--- a/docs/grub.texi
+++ b/docs/grub.texi
@@ -3214,6 +3214,12 @@ These variables have special meaning to GRUB.
 * gfxterm_font::
 * grub_cpu::
 * grub_platform::
+* grub_ver::
+* grub_ver_major::
+* grub_ver_minor::
+* grub_ver_git_commit::
+* grub_ver_oem::
+* grub_git
 * icondir::
 * lang::
 * locale_dir::
@@ -3493,6 +3499,66 @@ In normal mode (@pxref{normal}), GRUB sets the 
@samp{grub_platform} variable
 to the platform for which GRUB was built (e.g. @samp{pc} or @samp{efi}).
 
 
+@node grub_ver
+@subsection grub_ver
+
+In normal mode (@pxref{normal}), GRUB sets the @samp{grub_ver} variable to the
+current GRUB version (i.e. @value{VERSION}).
+
+In its complete form, the @samp{grub_ver} variable is composed of four
+parameters:
+@itemize @bullet
+@item
+@samp{major}: the major version number (mandatory and automatically added;
+@pxref{grub_ver_major})
+@item
+@samp{minor}: the minor version number (mandatory and automatically added;
+@pxref{grub_ver_minor})
+@item
+@samp{git}: the GIT current commit hash number (optional,
+@pxref{grub_ver_git_commit})
+@item
+@samp{oem}: the OEM custom number/string (optional, @pxref{grub_ver_oem})
+@end itemize
+
+The above four parameters are assembled as:
+
+@samp{major.minor[.git][-oem]}
+
+To enable the two optional version items (@samp{git} and @samp{oem}), see the
+file @file{VERSION} in the GRUB source code.
+
+@node grub_ver_major
+@subsection grub_ver_major
+
+In normal mode (@pxref{normal}), GRUB sets the @samp{grub_ver_major} variable 
to
+the current GRUB major version (@pxref{grub_ver}).
+
+@node grub_ver_minor
+@subsection grub_ver_minor
+
+In normal mode (@pxref{normal}), GRUB sets the @samp{grub_ver_minor} variable 
to
+the current GRUB minor version (@pxref{grub_ver}).
+
+@node grub_ver_git_commit
+@subsection grub_ver_git_commit
+
+In normal mode (@pxref{normal}), GRUB can sets the @samp{grub_ver_git_commit}
+variable to the current GRUB commit (@pxref{grub_ver}). In other words, this 
version is
+simply the GIT SHA-1 hash (in short form), of the current commit of the GRUB 
GIT
+repository.
+To enable @samp{grub_ver_git_commit}, see the file @file{VERSION} in the GRUB
+source code.
+
+@node grub_ver_oem
+@subsection grub_ver_oem
+
+In normal mode (@pxref{normal}), GRUB can sets the @samp{grub_ver_oem} variable
+to a custom number/string (256 chars max) decided by the OEM who has customized
+the GRUB source code (@pxref{grub_ver}).
+To enable @samp{grub_ver_oem}, see the file @file{VERSION} in the GRUB
+source code.
+
 @node icondir
 @subsection icondir
 
diff --git a/grub-core/normal/main.c b/grub-core/normal/main.c
index c4ebe9e..df5f6db 100644
--- a/grub-core/normal/main.c
+++ b/grub-core/normal/main.c
@@ -512,6 +512,7 @@ static const char *features[] = {
 GRUB_MOD_INIT(normal)
 {
   unsigned i;
+  char tmp_str[256];
 
   grub_boot_time ("Preparing normal module");
 
@@ -563,11 +564,40 @@ GRUB_MOD_INIT(normal)
       grub_env_set (features[i], "y");
       grub_env_export (features[i]);
     }
+
+  /* Set env vars for cpu and platform names */
   grub_env_set ("grub_cpu", GRUB_TARGET_CPU);
   grub_env_export ("grub_cpu");
   grub_env_set ("grub_platform", GRUB_PLATFORM);
   grub_env_export ("grub_platform");
 
+  /* Set env var for complete version */
+  grub_env_set ("grub_ver", PACKAGE_VERSION);
+
+  /* Set env vars for major and minor versions (see VERSION file) */
+  grub_env_set ("grub_ver_major", PACKAGE_VERSION_MAJOR);
+  grub_env_export ("grub_ver_major");
+  grub_env_set ("grub_ver_minor", PACKAGE_VERSION_MINOR);
+  grub_env_export ("grub_ver_minor");
+
+  /* Set env var for version about git commit hash (see VERSION file) */
+  grub_memset (tmp_str, 0, sizeof(tmp_str));
+  grub_strcpy (tmp_str, PACKAGE_VERSION_GIT_COMMIT);
+  if (grub_strlen (tmp_str) != 0)
+    {
+      grub_env_set ("grub_ver_git_commit", PACKAGE_VERSION_GIT_COMMIT);
+      grub_env_export ("grub_ver_git_commit");
+    }
+
+  /* Set env var for OEM version */
+  grub_memset (tmp_str, 0, sizeof(tmp_str));
+  grub_strcpy (tmp_str, PACKAGE_VERSION_OEM);
+  if (grub_strlen (tmp_str) != 0)
+    {
+      grub_env_set ("grub_ver_oem", PACKAGE_VERSION_OEM);
+      grub_env_export ("grub_ver_oem");
+    }
+
   grub_boot_time ("Normal module prepared");
 }
 
-- 
2.7.4