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

[Glenn Washburn]

On Mon, 27 Apr 2020 13:50:03 +0200
Flavio Suligoi <f.suligoi@asem.it> wrote:

> 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 <f.suligoi@asem.it>
> Reviewed-by: Paul Menzel <pmenzel@molgen.mpg.de>
> Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>

Is there a reason this hasn't been committed yet? It seems like a good
idea and has been reviewed. Perhaps forgotten? I think this would be
good to get in before the next release. There are some minor issues
that I think should be fixed/changed before inclusion (see below).

> ---
> 
> 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

s/indipendent/independent/

> +#       also enabled simultaneously.
> +#
> +# IMPORTANT: don't insert spaces inside any version number/string.

s/don't/Don't/

> +# IMPORTANT: run again the commands:

s/run/Run/

> +#
> +#              ./bootstrap
> +#              ./configure
> +#              ./autogen.sh
> +#
> +#            after changing also only one of the version elements.
> +#
> +
> +MAJOR 2
> +MINOR 05

This of course will now change to 11 if this gets in before the release.

> +# 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],[bug-grub@gnu.org])
> +# 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],[bug-grub@gnu.org])
> +
> +# 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,

s/bugfixex/bug fixes/

> +...). 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

I think this line should be removed. First of all there's a sntactic
issue, and second I don't see a variable grub_git mentioned anywhere
else.

>  * 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];

This can be done away with, see below.

>  
>    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);

Does this not need to be exported?

> +
> +  /* 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");
> +    }

I would suggest the following to replace the lines up to the next new
line: 

   /* Set env var for version about git commit hash (see VERSION file)
   */ if (grub_strlen (PACKAGE_VERSION_GIT_COMMIT) != 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");
> +    }
> +

Same as above.

Glen

>    grub_boot_time ("Normal module prepared");
>  }
>