[PATCH v3 01/12] README: Add doumentation for version information

[Bin Meng]

Hi Simon,

On Mon, Jan 25, 2021 at 1:50 AM Simon Glass <sjg at chromium.org> wrote:
>
> There are quite a few available version options in U-Boot. Add a list of
> the available Makefile variables and #defines, along with examples.
>
> Signed-off-by: Simon Glass <sjg at chromium.org>
> ---
>
> Changes in v3:
> - Move to doc/ and .rst format
> - Add examples for converting epoch values
>
>  doc/Makefile            |  1 -
>  doc/develop/index.rst   |  1 +
>  doc/develop/version.rst | 93 +++++++++++++++++++++++++++++++++++++++++
>  3 files changed, 94 insertions(+), 1 deletion(-)
>  create mode 100644 doc/develop/version.rst
>
> diff --git a/doc/Makefile b/doc/Makefile
> index a686d4728ec..683e4b56099 100644
> --- a/doc/Makefile
> +++ b/doc/Makefile
> @@ -56,7 +56,6 @@ quiet_cmd_sphinx = SPHINX  $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
>         PYTHONDONTWRITEBYTECODE=1 \
>         BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \
>         $(SPHINXBUILD) \
> -       -W \

Why is this change?

>         -b $2 \
>         -c $(abspath $(srctree)/$(src)) \
>         -d $(abspath $(BUILDDIR)/.doctrees/$3) \
> diff --git a/doc/develop/index.rst b/doc/develop/index.rst
> index beaa64d8d90..ac57fdb8f30 100644
> --- a/doc/develop/index.rst
> +++ b/doc/develop/index.rst
> @@ -13,6 +13,7 @@ Implementation
>     global_data
>     logging
>     menus
> +   version
>
>  Debugging
>  ---------
> diff --git a/doc/develop/version.rst b/doc/develop/version.rst
> new file mode 100644
> index 00000000000..6da31a4a1e7
> --- /dev/null
> +++ b/doc/develop/version.rst
> @@ -0,0 +1,93 @@
> +.. SPDX-License-Identifier: GPL-2.0+
> +.. Copyright (c) 2013 The Chromium OS Authors.
> +
> +Version information
> +===================
> +
> +U-Boot releases are named by year and patch level, for example 2020.10 means the
> +release that came out in October 2020. Release candidates are tagged every few
> +weeks as the project heads to the next release. So 2020.10-rc1 was the first
> +release candidate (RC), tagged soon after 2020.07 was released.
> +
> +See https://www.denx.de/wiki/view/U-Boot/ReleaseCycle for full details.
> +
> +Within the build system, various Makefile variables are created, making use of
> +VERSION, PATCHLEVEL and EXTRAVERSION defined at the top of 'Makefile'. There is
> +also SUBLEVEL available for downstream use. See also CONFIG_IDENT_STRING.
> +
> +Some variables end up in a generated header file at
> +include/generated/version_autogenerated.h and can be accessed from C source by
> +including <version.h>
> +
> +The following are available:
> +
> +   UBOOTRELEASE (Makefile)
> +      Full release version as a string. If this is not a tagged release, it also
> +      includes the number of commits since the last tag as well as the the git
> +      hash.  If there are uncommitted changes a '-dirty' suffix is added too.
> +
> +      This is written by scripts/setlocalversion (maintained by Linux) to
> +      include/config/uboot.release and ends up in the UBOOTRELEASE Makefile
> +      variable.
> +
> +      Examples::
> +
> +         2020.10-rc3
> +         2021.01-rc5-00248-g60dd854f3ba-dirty
> +
> +   PLAIN_VERSION (string #define)
> +      This is UBOOTRELEASE but available in C source.
> +
> +      Examples::
> +
> +         2020.10
> +         2021.01-rc5-00248-g60dd854f3ba-dirty
> +
> +   UBOOTVERSION (Makefile)
> +      This holds just the first three components of UBOOTRELEASE (i.e. not the
> +      git hash, etc.)
> +
> +      Examples::
> +
> +         2020.10
> +         2021.01-rc5
> +
> +   U_BOOT_VERSION (string #define)
> +      "U-Boot " followed by UBOOTRELEASE, for example::
> +
> +         U-Boot 2020.10
> +         U-Boot 2021.01-rc5
> +
> +      This is used as part of the banner string when U-Boot starts.
> +
> +   U_BOOT_VERSION_STRING (string #define)
> +      U_BOOT_VERSION followed by build-time information
> +      and CONFIG_IDENT_STRING.
> +
> +      Examples::
> +
> +         U-Boot 2020.10 (Jan 06 2021 - 08:50:36 -0700)
> +         U-Boot 2021.01-rc5-00248-g60dd854f3ba-dirty (Jan 06 2021 - 08:50:36 -0700) for spring
> +
> +Build date/time is also included. See the generated file
> +include/generated/timestamp_autogenerated.h for the available
> +fields. For example::
> +
> +   #define U_BOOT_DATE "Jan 06 2021"     (US format only)
> +   #define U_BOOT_TIME "08:50:36"        (24-hour clock)
> +   #define U_BOOT_TZ "-0700"             (Time zone in hours)
> +   #define U_BOOT_DMI_DATE "01/06/2021"  (US format only)
> +   #define U_BOOT_BUILD_DATE 0x20210106  (hex yyyymmdd format)
> +   #define U_BOOT_EPOCH 1609948236
> +
> +The Epoch is the number of seconds since midnight on 1/1/70. You can convert
> +this to a time with::
> +
> +   $ date -u -d @1609948236
> +   Wed 06 Jan 2021 03:50:36 PM UTC
> +   $ date -d 'Wed 06 Jan 2021 03:50:36 PM UTC' +%s
> +   1609948236
> +
> +Every time you build U-Boot this will update based on the time
> +on your build machine. See 'Reproducible builds' if you want to
> +avoid that.

Otherwise,
Reviewed-by: Bin Meng <bmeng.cn at gmail.com>