build: add version-sync lint and ship notices in install and release

Add tests/check-version (wired into `make lint`) asserting VERSION matches the
man-page versions and that CITATION.cff carries a released version and date,
plus a `make bump-version NEW=x.y.z` target that updates VERSION, the man-page
dates/versions, and CITATION.cff together.

Install THIRD-PARTY-NOTICES.md alongside LICENSE and copy it into the release
tarball, so the attribution travels with every distributed copy.

Author: bcoles

.github/workflows/_cross-build.yml

@@ -179,7 +179,7 @@ jobs:
           cp -a "${{ steps.builddir.outputs.dir }}/." "${DIR}/"
           rm -rf "${DIR}/obj"
           find "${DIR}/components" -type f ! -perm -u+x -delete
-          cp README.md LICENSE "${DIR}/"
+          cp README.md LICENSE THIRD-PARTY-NOTICES.md "${DIR}/"
           # Companion symbol-offset tool (arch-independent) + the docs, so the
           # tarball matches `make install` and the README's doc links resolve.
           mkdir -p "${DIR}/extra"

Makefile

@@ -616,6 +616,7 @@ lint :
 	@$(TEST_DIR)/check-fdt-unflatten
 	@$(TEST_DIR)/check-ksymoff
 	@$(TEST_DIR)/check-manpages
+	@$(TEST_DIR)/check-version
 	@$(TEST_DIR)/check-posture-diff
 	@$(TEST_DIR)/check-posture-summary
 	@$(TEST_DIR)/check-shellcheck
@@ -768,7 +769,7 @@ install : build
 	  install -m 755 "$$f" "$(DESTDIR)$(PREFIX)/libexec/kasld/"; \
 	done
 	install -d "$(DESTDIR)$(PREFIX)/share/doc/kasld"
-	cp -R docs README.md LICENSE "$(DESTDIR)$(PREFIX)/share/doc/kasld/"
+	cp -R docs README.md LICENSE THIRD-PARTY-NOTICES.md "$(DESTDIR)$(PREFIX)/share/doc/kasld/"
 	install -d "$(DESTDIR)$(PREFIX)/share/man/man1"
 	install -m 644 man/kasld.1 man/ksymoff.1 "$(DESTDIR)$(PREFIX)/share/man/man1/"
 
@@ -885,6 +886,30 @@ print-deps:
 	@echo "  Build-Depends:            gcc, make, libc-dev"
 	@echo "  Build-Depends (optional): zlib1g-dev   (pthread ships in libc6)"
 
+# Stamp a new version across the files that carry it as metadata: the VERSION
+# file (injected into the build as -DVERSION), the man-page .TH lines (version +
+# date), and — for a real release only — CITATION.cff (version + date-released;
+# a -dev string is not a citable identifier). The usage.md example output is
+# illustrative and intentionally not stamped. tests/check-version enforces that
+# these stay in step. Uses GNU sed -i.
+#   make bump-version NEW=0.3.1        # cut a release
+#   make bump-version NEW=0.3.2-dev    # open the next dev cycle
+.PHONY: bump-version
+bump-version :
+	@[ -n "$(NEW)" ] || { echo 'usage: make bump-version NEW=x.y.z  (append -dev for a dev cycle)' >&2; exit 2; }
+	@new='$(NEW)'; d=$$(date +%F); old=$$(cat VERSION 2>/dev/null); \
+	printf '%s\n' "$$new" > VERSION; \
+	for m in man/kasld.1 man/ksymoff.1; do \
+	  sed -i -E "1s/\"[0-9]{4}-[0-9]{2}-[0-9]{2}\"/\"$$d\"/; 1s/\"kasld [^\"]*\"/\"kasld $$new\"/" "$$m"; \
+	done; \
+	case "$$new" in \
+	*-dev) echo "  note: '$$new' is a dev version — CITATION.cff left at the last release" ;; \
+	*) sed -i -E "s/^version: .*/version: \"$$new\"/; s/^date-released: .*/date-released: \"$$d\"/" CITATION.cff; \
+	   echo "  CITATION.cff -> version $$new, date-released $$d" ;; \
+	esac; \
+	echo "  VERSION: $${old:-?} -> $$new   (man pages dated $$d)"; \
+	echo "  next: review the diff, commit, and 'git tag v$$new' for a release"
+
 .PHONY: help
 help:
 	@echo
@@ -901,6 +926,7 @@ help:
 	@echo "      uninstall       Remove installed files"
 	@echo "      clean           Remove build directory"
 	@echo "      print-deps      List build dependencies (libs + per-component flags)"
+	@echo "      bump-version    Stamp NEW=x.y.z across VERSION, man pages, CITATION.cff"
 	@echo
 	@echo "  Test targets:"
 	@echo "      test                   Build and run the unit suite + lint"

tests/check-version

@@ -0,0 +1,66 @@
+#!/bin/sh
+# This file is part of KASLD - https://github.com/bcoles/kasld
+#
+# check-version — the version-carrying files stay in step, so a release does
+# not ship a binary that says one version while the man pages say another.
+#
+# Asserts:
+#   - man/kasld.1 and man/ksymoff.1 `.TH` version == the VERSION file
+#     (roff `\-` escapes are normalized before comparing).
+#   - CITATION.cff has a `version:` and a `date-released:`, and the cited
+#     version is a real release (not an in-development `-dev` string, which is
+#     not a citable identifier — cite a release or a commit instead).
+#
+# `make bump-version V=x.y.z` updates all of these together.
+#
+# Usage: tests/check-version   (also run by `make test`)
+# ---
+# <bcoles@gmail.com>
+
+set -u
+ROOT=$(CDPATH='' cd -- "$(dirname -- "$0")/.." && pwd)
+
+if [ -t 2 ]; then
+  RED=$(printf '\033[31m')
+  GREEN=$(printf '\033[32m')
+  RESET=$(printf '\033[0m')
+else
+  RED=
+  GREEN=
+  RESET=
+fi
+
+fails=0
+fail() {
+  printf '%scheck-version: FAIL%s — %s\n' "$RED" "$RESET" "$1" >&2
+  fails=$((fails + 1))
+}
+
+ver=$(cat "$ROOT/VERSION" 2>/dev/null)
+[ -n "$ver" ] || fail "VERSION file is empty or missing"
+
+# Man-page .TH version: `"kasld <version>"`, with roff `\-` normalized to `-`.
+for m in kasld ksymoff; do
+  mf="$ROOT/man/$m.1"
+  mver=$(sed -n '1s/.*"kasld \([^"]*\)".*/\1/p' "$mf" | sed 's/\\//g')
+  [ "$mver" = "$ver" ] ||
+    fail "man/$m.1 version '$mver' != VERSION '$ver' (run: make bump-version V=$ver)"
+done
+
+# CITATION.cff cites a released version (never -dev), with a release date.
+cff="$ROOT/CITATION.cff"
+if [ -f "$cff" ]; then
+  cver=$(sed -n 's/^version: *"\([^"]*\)".*/\1/p' "$cff" | head -1)
+  grep -q '^date-released:' "$cff" || fail "CITATION.cff: no date-released"
+  case "$cver" in
+  "") fail "CITATION.cff: no version" ;;
+  *-dev) fail "CITATION.cff cites '$cver' — cite a release, not a -dev string" ;;
+  esac
+fi
+
+if [ "$fails" -ne 0 ]; then
+  exit 1
+fi
+
+printf '%scheck-version: OK%s (VERSION %s in step with man pages; CITATION.cff cites a release)\n' \
+  "$GREEN" "$RESET" "$ver"