build: keep full git version out of config.h (ccache-friendly)

INSTALL.nut.adoc

@@ -279,13 +279,19 @@ for developers iterating on some features.
   changed. On many systems it suffices to add e.g. `/usr/lib/ccache` early
   in `PATH` and populate it with symlinks to e.g. `/usr/bin/ccache` using
   various compiler program names.
-* If you are a developer iterating with debug builds on different branches,
-  `export CI_AUTOGEN_STABLE_VERSION=true` can additionally ensure that the
-  `AC_INIT` in the generated `configure` script would not follow NUT SEMVER
-  but use a shorter and temporally stable version string. This helps on some
-  systems where enabling debug options embeds all macros into compiled objects,
-  so an ever-changing `PACKAGE_VERSION` in `config.h` which does follow NUT
-  SEMVER prevents `ccache` direct mode (because each build is deemed unique).
+  The full Git-derived NUT version, which changes with every commit, is not
+  stored in the `include/config.h` file (included by all sources) but only
+  in `include/nut_version.h` (included by a couple of source files), so after
+  a new commit or in a fresh checkout, only those few objects get recompiled.
+  This matters especially for debug builds with options like `-g3` which
+  embed all macro definitions into compiled objects, so `ccache` can not
+  fall back to its preprocessor mode to find a match for a changed macro.
+  If several Git work trees or checkout directories share one cache, set
+  `CCACHE_BASEDIR` to a common parent directory so that absolute paths in
+  compiler command lines do not prevent cache hits.
+* When you iterate code development, `make NUT_VERSION_H_GENERATED=true`
+  can skip regeneration of `include/nut_version.h` (at a cost of a less
+  precise version reported by the built programs).
 * Using `export DO_USE_NUTCI_CACHE=yes` (and derived environment variables
   like `DO_USE_AUTOCONF_CACHE` or `DO_USE_NIT_TESTCERT_CACHE`) can be used
   to speed up re-builds with `ci_build.sh` and re-runs of NUT Integration

NEWS.adoc

@@ -1048,6 +1048,13 @@ https://github.com/networkupstools/nut/milestone/13
       with both a current and an old (7.1, as on CentOS 7) version of the
       `aspell-en` dictionary. Local builds keep the default of
       `configure --enable-spellcheck=auto`. [PR #3752]
+    * The `include/config.h` file no longer carries the full Git-derived NUT
+      version (which changes with every commit), only the base semantic
+      version (e.g. `2.8.5` for a release, or `2.8.5.1` for any development
+      iteration after it), so `ccache` and similar build caches can re-use
+      compiled objects across commits and fresh CI checkouts. The full
+      version is still provided by `include/nut_version.h` and in the
+      substituted `@PACKAGE_VERSION@` values. [PR #3759, follow-up to PR #3754]
     * The `make shellcheck` (and `make check-scripts-syntax`) recipe can now
       check the POSIX shell scripts with each interpreter listed in the
       `SHELL_PROGS` environment variable (default is still the system

UPGRADING.adoc

@@ -33,6 +33,18 @@ Changes from 2.8.5 to 2.8.6
 
 - PLANNED: Keep track of any further API clean-up?
 
+- The `PACKAGE_VERSION` and `PACKAGE_STRING` macros in the generated
+  `include/config.h` now only carry the base semantic version (e.g. `2.8.5`
+  for a release, or `2.8.5.1` for any development iteration after it) rather
+  than the full Git-derived version (e.g. `2.8.5.1466.13`), and the
+  `PACKAGE` and `VERSION` macros are no longer defined there, so that build
+  caches remain valid across commits. The `./configure --version` output
+  also reports this shortened version. Code which needs the full version
+  should use `NUT_VERSION_MACRO` from the generated `include/nut_version.h`.
+  The `@PACKAGE_VERSION@` and `@VERSION@` values substituted into Makefiles,
+  `*.pc` files, packaging recipes and tarball names are not changed.
+  [PR #3754 follow-up]
+
 - The Perl `UPS::Nut` module now decodes NUT quoting and backslash escapes
   in query/list values and `nutauth.conf`, including include paths. Remove
   manual decoding of these returned values and pass literal credentials

appveyor.yml

@@ -35,9 +35,6 @@ environment:
   # ccache max_size is capped below (see install steps) to leave a margin
   # for the other entries (pacman packages ~100MB, nut-win-deps, nut-ci):
   APPVEYOR_CACHE_ENTRY_ZIP_ARGS: -t7z -mx=0
-  # Keep config.h stable across PRs, so ccache can reuse -g3 objects
-  # (see ci_build.sh for details):
-  CI_AUTOGEN_STABLE_VERSION: true
   CCACHE_DIR: /home/appveyor/.ccache
   DO_CLEAN_NUTCI_CACHE: no
   DO_USE_NUTCI_CACHE: yes

ci_build.sh

@@ -1136,32 +1136,11 @@ do_autogen_get_CONFIGURE_SCRIPT() {
         # older system) we have to remove it when we already have the script.
         # This matches the use-case of distro-building from release tarballs that
         # include all needed pre-generated files to rely less on OS facilities.
-        (
-            # Optionally drop the PR-specific last component of the version
-            # (e.g. 2.8.5.1466.13 => 2.8.5.1466) which AC_INIT puts into
-            # config.h as PACKAGE_VERSION. The ccache direct mode hashes all
-            # included headers, so a version change misses for nearly every
-            # file and defeats ccache across pull requests. Only autogen.sh gets
-            # this setting, so `make` still generates nut_version.h (and the
-            # UPS_VERSION reported by programs) from actual Git metadata.
-            if [ x"${CI_AUTOGEN_STABLE_VERSION-}" = xtrue ] && [ -z "${NUT_VERSION_FORCED-}" ] ; then
-                _NUT_VERSION_STABLE="`NUT_VERSION_QUERY=VER50 ./tools/gitlog2version.sh 2>/dev/null`" || _NUT_VERSION_STABLE=""
-                case "${_NUT_VERSION_STABLE}" in
-                    *.*.*.*.*) _NUT_VERSION_STABLE="${_NUT_VERSION_STABLE%.*}" ;;
-                esac
-                if [ -n "${_NUT_VERSION_STABLE}" ] ; then
-                    echo "INFO: CI_AUTOGEN_STABLE_VERSION: using NUT_VERSION_FORCED='${_NUT_VERSION_STABLE}' for autogen.sh" >&2
-                    NUT_VERSION_FORCED="${_NUT_VERSION_STABLE}"
-                    export NUT_VERSION_FORCED
-                fi
-            fi
-
-            if [ "$CI_OS_NAME" = "windows" ] ; then
-                $CI_TIME ./autogen.sh || true
-            else
-                $CI_TIME ./autogen.sh ### 2>/dev/null
-            fi
-        ) || exit
+        if [ "$CI_OS_NAME" = "windows" ] ; then
+            $CI_TIME ./autogen.sh || true
+        else
+            $CI_TIME ./autogen.sh ### 2>/dev/null
+        fi || exit
     fi
 
     # Retain the full path to configure script file

configure.ac

@@ -23,12 +23,28 @@ dnl See https://github.com/networkupstools/nut/issues/1949 for details.
 dnl Oddly, autoconf-2.69 on CentOS 7 both complains that AC INIT argument
 dnl is not a literal, and does contain expected values in the generated
 dnl script and include/config.h. A "pure" m4 solution would be quieter.
+dnl NOTE: AC_INIT gets the base SEMVER for releases (e.g. "2.8.5"), and a
+dnl nominal "SEMVER.1" for any development iteration after it (e.g. "2.8.5.1"),
+dnl which does not change between releases. It ends up in include/config.h
+dnl as PACKAGE_VERSION and PACKAGE_STRING macros, and every source file
+dnl includes config.h, so with
+dnl the full git-derived version there every new commit would invalidate all
+dnl compiled objects in ccache (direct mode) or similar build caches. The
+dnl full version (VER50, e.g. "2.8.5.1466.13") is assigned to the shell
+dnl variables right below, so all AC_SUBST'ed @PACKAGE_VERSION@ and friends
+dnl (Makefiles, *.pc files, packaging recipes, tarball names) are not changed.
+dnl C code should use NUT_VERSION_MACRO from include/nut_version.h which is
+dnl generated by make and only consumed by a couple of source files.
 AC_INIT([nut],
-    m4_esyscmd_s([NUT_VERSION_QUERY=VER50 "`dirname \"$0\"`/tools/gitlog2version.sh" 2>/dev/null]),
+    m4_esyscmd_s([NUT_VERSION_QUERY=SEMVER_ACINIT "`dirname \"$0\"`/tools/gitlog2version.sh" 2>/dev/null]),
     [https://github.com/networkupstools/nut/issues],[nut],
     m4_esyscmd_s([NUT_VERSION_QUERY=URL "`dirname \"$0\"`/tools/gitlog2version.sh" 2>/dev/null]))
 dnl See docs/maintainer-guide.txt about releases - updating the version
 dnl above is a small part of the consistent ritual!
+NUT_ACINIT_VERSION="${PACKAGE_VERSION}"
+PACKAGE_VERSION='m4_esyscmd_s([NUT_VERSION_QUERY=VER50 "`dirname \"$0\"`/tools/gitlog2version.sh" 2>/dev/null])'
+test -n "${PACKAGE_VERSION}" || PACKAGE_VERSION="${NUT_ACINIT_VERSION}"
+PACKAGE_STRING="${PACKAGE_NAME} ${PACKAGE_VERSION}"
 
 dnl Detect usable grep and egrep as soon as possible, to let called scripts
 dnl use them. Unfortunately, init must happen before macros that output text,
@@ -218,7 +234,11 @@ AC_SUBST([NUT_CONFIG_LDFLAGS])
 NUT_STASH_WARNINGS
 AC_CONFIG_HEADERS([include/config.h])
 AC_PREFIX_DEFAULT(/usr/local/ups)
-AM_INIT_AUTOMAKE([subdir-objects tar-pax])
+dnl Do not define PACKAGE and VERSION macros in config.h (not used by code);
+dnl the VERSION substitution would be the AC_INIT SEMVER, so (re-)set it to
+dnl the full version for Makefile purposes (distdir, tarball names...)
+AM_INIT_AUTOMAKE([subdir-objects tar-pax no-define])
+VERSION="${PACKAGE_VERSION}"
 
 AS_CASE([${target_os}],
 	[*mingw*], [AS_CASE([${CFLAGS-}${CXXFLAGS-}],

docs/developers.txt

@@ -336,6 +336,16 @@ build agent preparation,NUTCI_farm_agents].
 See also "Repetitive build/test optimizations" in `INSTALL.nut.adoc` file
 for suggestions specific to this area.
 
+The full Git-derived NUT version (e.g. `2.8.5.1466.13`) changes with every
+commit, so it is kept out of `include/config.h` (included by all sources)
+to let `ccache` re-use objects: the `PACKAGE_VERSION` and `PACKAGE_STRING`
+macros there only carry the base semantic version (e.g. `2.8.5`, or
+`2.8.5.1` for any development iteration after that release). Please
+do not use these macros in new C code; the full version is provided by
+`NUT_VERSION_MACRO` in the generated `include/nut_version.h` file (exposed
+to programs by the `UPS_VERSION` string in common code), and that header
+should not be included by more source files than necessary.
+
 Integrated Development Environments (IDEs) and debugging NUT
 ------------------------------------------------------------
 

docs/nut-versioning.adoc

@@ -322,6 +322,13 @@ DESC='v2.8.2-2381+g1faa9945d'
 			  * DESC5X with default width (6):
 			    `000002.000008.000004.000910.000002-912+g081755da0`
 |`SEMVER`	| Exactly three leading numeric components	| * `2.8.2`
+|`SEMVER_ACINIT`	| `SEMVER` for releases, or a nominal `SEMVER.1` for any
+			  development iteration after that release (for pre-releases,
+			  the triplet of `VER50` is used, unless forced otherwise).
+			  Used for `AC_INIT` (so ends up in `config.h` macros), and
+			  does not change between releases, to benefit build caches.
+			| * dev: `2.8.2.1`
+			  * rel: `2.8.2`
 |`IS_RELEASE`	| `true` if `SEMVER`==`VER50`, `false` otherwise
 			| * dev: `false`
 			  * rel: `true`

docs/nut.dict

@@ -1,9 +1,10 @@
-personal_ws-1.1 en 3916 utf-8
+personal_ws-1.1 en 3917 utf-8
 AAC
 AAS
 ABI
 ACFAIL
 ACFREQ
+ACINIT
 ACK
 ACM
 ACPI