common: support custom, extra information for build's version

This patch adds a system of extra version information also found in
LTTng-tools.

`src/common/Makefile` generates `src/common/version.i` at every build.
This file contains:

* The current Git revision description.

* Extra name of the version (found in `version/extra_version_name`).

* Extra description of the version (found in
  `version/extra_version_description`).

* A list of patch file names found in `version/extra_patches`.

All definitions can be empty strings.

See `version/README.adoc` to learn more.

As of this patch, libbabeltrace2 does not offer getters for this data
and the CLI does not print it with the `--version` option. This is
reserved for subsequent patches.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: Ife50e5bcaa6b3bdeda6ee4e7c1fdeb2fb1f63887
Reviewed-on: https://review.lttng.org/c/babeltrace/+/2836
Reviewed-by: Francis Deslauriers <francis.deslauriers@efficios.com>
Reviewed-by: Michael Jeanson <mjeanson@efficios.com>
Tested-by: jenkins <jenkins@lttng.org>

.gitignore

@@ -69,3 +69,4 @@ cscope*
 *.swp
 .theia
 compile_commands.json
+/version

Makefile.am

@@ -10,3 +10,5 @@ dist_doc_DATA = ChangeLog LICENSE mit-license.txt gpl-2.0.txt \
 		std-ext-lib.txt README.adoc CONTRIBUTING.adoc
 
 dist_noinst_DATA = CodingStyle
+
+EXTRA_DIST = version

src/cli/babeltrace2-cfg-cli-args.c

@@ -197,10 +197,10 @@ void plugin_comp_cls_names(const char *arg, char **name, char **plugin,
 static
 void print_version(void)
 {
-	if (GIT_VERSION[0] == '\0') {
+	if (BT_VERSION_GIT[0] == '\0') {
 		puts("Babeltrace " VERSION);
 	} else {
-		puts("Babeltrace " VERSION  " - " GIT_VERSION);
+		puts("Babeltrace " VERSION  " - " BT_VERSION_GIT);
 	}
 }
 

src/common/Makefile.am

@@ -15,9 +15,9 @@ noinst_HEADERS = \
 	list.h \
 	macros.h \
 	mmap-align.h \
-	safe.h \
-	version.h \
-	version.i
+	safe.h
+
+# The following section is based on a similar feature in LTTng-tools.
 
 ##
 ## This target generates an include file that contains the git version
@@ -41,34 +41,61 @@ noinst_HEADERS = \
 ## overwrite the git version with an empty string in "version.i.tmp".
 ##
 ## If we don't have a "version.i.tmp" nor a "version.i", generate an empty
-## string as a failover.
+## string as a failover. If a "version.i" is present, for example when building
+## from a distribution tarball, get the git_version using grep.
 ##
-## If we don't have a "version.i" or we have both files and they are different,
-## copy "version.i.tmp" over "version.i". This way the dependent targets are
-## only rebuilt when the version string changes.
+## Fetch the BT_VERSION_EXTRA_NAME define from "version/extra_version_name" and output it
+## to "version.i.tmp".
+##
+## Fetch the BT_VERSION_EXTRA_DESCRIPTION define from "version/extra_version_description",
+## sanitize and format it with a sed script to replace all non-alpha-numeric values
+## with "-" and join all lines by replacing "\n" with litteral string c-style "\n" and
+## output it to "version.i.tmp".
+##
+## Repeat the same logic for the "version/extra_patches" directory.
+## Data fetched from "version/extra_patches" must be sanitized and
+## formatted.
+## The data is fetched using "ls" with an ignore pattern for the README.adoc file.
+## The sanitize step uses sed with a script to replace all
+## non-alpha-numeric values, except " " (space), to "-".
+## The formatting step uses sed with a script to join all lines
+## by replacing "\n" with litteral string c-style "\n".
+##
+## If we don't have a "version.i" or we have both files (version.i, version.i.tmp)
+## and they are different, copy "version.i.tmp" over "version.i".
+## This way the dependent targets are only rebuilt when the git version
+## string or either one of extra version string change.
 ##
-
 version_verbose = $(version_verbose_@AM_V@)
 version_verbose_ = $(version_verbose_@AM_DEFAULT_V@)
-version_verbose_0 = @echo "  GEN     " $@;
+version_verbose_0 = @echo "  GEN       " $@;
 
 version.i:
 	$(version_verbose)rm -f version.i.tmp; \
+	if (test ! -f version.i && test -f "$(top_srcdir)/include/version.i"); then \
+		cp "$(top_srcdir)/include/version.i" version.i; \
+	fi; \
 	if (test -r "$(top_srcdir)/bootstrap" && test -r "$(top_srcdir)/.git") && \
 			test -x "`which git 2>&1;true`"; then \
 		GIT_VERSION_STR="`cd "$(top_srcdir)" && git describe --tags --dirty`"; \
 		GIT_CURRENT_TAG="`cd "$(top_srcdir)" && git describe --tags --exact-match --match="v[0-9]*" HEAD 2> /dev/null`"; \
-		echo "#define GIT_VERSION \"$$GIT_VERSION_STR\"" > version.i.tmp; \
+		echo "#define BT_VERSION_GIT \"$$GIT_VERSION_STR\"" > version.i.tmp; \
 		if ! $(GREP) -- "-dirty" version.i.tmp > /dev/null && \
 				test "x$$GIT_CURRENT_TAG" != "x"; then \
-			echo "#define GIT_VERSION \"\"" > version.i.tmp; \
+			echo "#define BT_VERSION_GIT \"\"" > version.i.tmp; \
 		fi; \
 	fi; \
 	if test ! -f version.i.tmp; then \
-		if test ! -f version.i; then \
-			echo '#define GIT_VERSION ""' > version.i; \
+		if test -f version.i; then \
+			$(GREP) "^#define \bBT_VERSION_GIT\b.*" version.i > version.i.tmp; \
+		else \
+			echo '#define BT_VERSION_GIT ""' > version.i.tmp; \
 		fi; \
-	elif test ! -f version.i || \
+	fi; \
+	echo "#define BT_VERSION_EXTRA_NAME \"`$(SED) -n '1p' "$(top_srcdir)/version/extra_version_name" 2> /dev/null`\"" >> version.i.tmp; \
+	echo "#define BT_VERSION_EXTRA_DESCRIPTION \"`$(SED) -E ':a ; N ; $$!ba ; s/[^a-zA-Z0-9 \n\t\.,]/-/g ; s/\r{0,1}\n/\\\n/g' "$(top_srcdir)/version/extra_version_description" 2> /dev/null`\"" >> version.i.tmp; \
+	echo "#define BT_VERSION_EXTRA_PATCHES \"`ls --ignore='README.adoc' -1 "$(top_srcdir)/version/extra_patches" | $(SED) -E ':a ; N ; $$!ba ; s/[^a-zA-Z0-9 \n\t\.]/-/g ; s/\r{0,1}\n/\\\n/g' 2> /dev/null`\"" >> version.i.tmp; \
+	if test ! -f version.i || \
 			test x"`cat version.i.tmp`" != x"`cat version.i`"; then \
 		mv version.i.tmp version.i; \
 	fi; \
@@ -88,3 +115,5 @@ CLEANFILES = version.i.tmp
 ## clean when it's part of a dist tarball.
 ##
 DISTCLEANFILES = version.i
+
+noinst_HEADERS += version.h version.i

version/README.adoc

@@ -0,0 +1,33 @@
+= Babeltrace's version extra information
+
+This directory contains files and a directory to add information to the
+version of a Babeltrace build. The CLI (`--version` option) and library
+can provide this information.
+
+The following directory and files are scanned at `src/common/version.i`
+generation time, which occurs at **every build**:
+
+`extra_version_name`::
+    If it exists, the first line of this file is the extra name of the
+    custom version.
+
+`extra_version_description`::
+    If it exists, the file's contents is the extra description of the
+    custom version.
++
+This should contain a description of local modifications applied to the
+source tree. A distribution packager can use this file, for example, to
+specify what changes were applied locally.
++
+All characters except alphanumeric ones, whitespaces, `.`, and `,` are
+replaced with `-`.
+
+`extra_patches`::
+    If it exists, this directory contains patch files applied to the
+    source tree.
++
+Each file name is included when generating `src/common/version.i`,
+except `README.adoc`.
++
+All characters except alphanumeric ones, whitespaces, and `.` are
+replaced with `-`.

version/extra_patches/README.adoc

@@ -0,0 +1,3 @@
+= Babeltrace's version extra information patches
+
+NOTE: See the parent directory's `README.adoc` file.