[libcamera-devel] [PATCH v2 1/2] utils: ABI Compatibility checker

[Kieran Bingham]

Provide support to compare ABI compatibility between any two git commits
or by a commit and the most recent ancestral tag of that commit.

Signed-off-by: Kieran Bingham <kieran.bingham at ideasonboard.com>
---
 utils/abi-compat.sh | 198 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 198 insertions(+)
 create mode 100755 utils/abi-compat.sh

diff --git a/utils/abi-compat.sh b/utils/abi-compat.sh
new file mode 100755
index 000000000000..b1944dc7d594
--- /dev/null
+++ b/utils/abi-compat.sh
@@ -0,0 +1,198 @@
+#!/bin/bash
+
+NAME=$(basename "$0")
+usage() {
+cat << EOF
+$NAME: Determine the ABI/API compatibility of two build versions
+
+  $NAME [--help] [--abi-dir=<PATH>] [--tmp-dir=<PATH>] ARGS
+
+The positional arguments (ARGS) determine the versions that will be compared and
+take three variants:
+
+  - No positional arguments:
+      $NAME [optional arguments]
+
+      It is assumed to compare the current git HEAD against the most recent TAG
+
+  - One positional argument:
+      $NAME [optional aguments] COMMITISH
+
+      The given COMMITISH is compared against it's most recent TAG
+
+  - Two positional arguments:
+      $NAME [optional aguments] BASE COMMITISH
+
+      The given COMMITISH is compared against the given BASE.
+
+Optional Arguments:
+  --abi-dir <path> Use <path> for storing (or retrieving existing) ABI data
+                   files
+
+  --tmp-dir <path> Specify temporary build location for building ABI data.
+                   This could be a tmpfs/RAM disk to save on disk writes.
+EOF
+}
+
+POSITIONAL=()
+while [[ $# -gt 0 ]]
+do
+case $1 in
+    -h|--help)
+        usage
+	exit 127;
+        ;;
+
+    --abi-dir)
+	ABI_DIR=$2
+	shift; shift;
+	;;
+
+    --tmp-dir)
+	TMP=$2
+	shift; shift;
+	;;
+
+    *)  # Parse unidentified arguments based on position
+        POSITIONAL+=("$1")
+        shift # past argument
+        ;;
+esac
+done
+set -- "${POSITIONAL[@]}" # restore positional parameters
+
+ABI_DIR=${ABI_DIR:-abi}
+TMP=${TMP:-"$ABI_DIR/tmp/"}
+
+mkdir -p "$ABI_DIR"
+mkdir -p "$TMP"
+
+dbg () {
+	echo "$@" >> /dev/stderr
+}
+
+die () {
+	echo "$NAME: $*" >> /dev/stderr
+	exit 128
+}
+
+prev_release () {
+	git describe --tags --abbrev=0 "$1"^ \
+		|| die "Failed to identify previous release tag from $1"
+}
+
+describe () {
+	git describe --tags "$@" \
+		|| die "Failed to describe $1"
+}
+
+# Make sure we exit on errors during argument parsing
+set -Eeuo pipefail
+
+# Check HEAD against previous 'release'
+if test $# -eq 0;
+then
+	FROM=$(prev_release HEAD)
+	TO=$(describe HEAD)
+fi
+
+# Check COMMIT against previous release
+if test $# -eq 1;
+then
+	FROM=$(prev_release "$1")
+	TO=$(describe "$1")
+fi
+
+# Check ABI between FROM and TO explicitly
+if test $# -eq 2;
+then
+	FROM=$(describe "$1")
+	TO=$(describe "$2")
+fi
+
+echo "Validating ABI compatibility between $FROM and $TO"
+
+# Generate an abi-compliance-checker xml description file
+# $PREFIX is assumed to be /usr/local/
+create_xml() {
+	# $1: Output file
+	# $2: Version
+	# $3: Install root
+
+	echo "<version>$2</version>" > "$1"
+	echo "<headers>$3/usr/local/include/</headers>" >> "$1"
+	echo "<libs>$3/usr/local/lib/</libs>" >> "$1"
+}
+
+# Check if an ABI dump file exists, and if not create one
+# by building a minimal configuration of libcamera at the specified
+# version using a clean worktree.
+create_abi_dump() {
+	VERSION="$1"
+	ABI_FILE="$ABI_DIR/$VERSION.abi.dump"
+	WORKTREE="$TMP/$VERSION"
+	BUILD="$TMP/$VERSION-build"
+
+	# Use a fully qualified path when calling ninja -C
+	INSTALL=$(realpath "$TMP/$VERSION-install")
+
+	if test ! -e "$ABI_FILE";
+	then
+		dbg "Creating ABI dump for $VERSION in $ABI_DIR"
+		git worktree add "$WORKTREE" "$VERSION"
+
+		meson setup "$BUILD" "$WORKTREE" \
+			-Ddocumentation=disabled \
+			-Dcam=disabled \
+			-Dqcam=disabled \
+			-Dgstreamer=disabled \
+			-Dlc-compliance=disabled \
+			-Dtracing=disabled \
+			-Dpipelines=
+
+		ninja -C "$BUILD"
+		DESTDIR="$INSTALL" ninja -C "$BUILD" install
+
+		# Create an xml descriptor with parameters to generate the dump file
+		create_xml \
+			"$INSTALL/libcamera-abi-dump.xml" \
+			"$VERSION" \
+			"$INSTALL"
+
+
+		# We currently have warnings produced that we can ignore
+		# While we have pipefail set, finish with || true
+		abi-compliance-checker \
+			-lib libcamera \
+			-v1 "$VERSION" \
+			-dump "$INSTALL/libcamera-abi-dump.xml" \
+			-dump-path "$ABI_FILE" || true
+
+		dbg Created "$ABI_FILE"
+
+		dbg Removing Worktree "$WORKTREE"
+		git worktree remove -f "$WORKTREE"
+
+		dbg Removing "$BUILD"
+		rm -r "$BUILD"
+
+		dbg Removing "$INSTALL"
+		rm -r "$INSTALL"
+	fi
+}
+
+# Create the requested ABI dump files if they don't yet exist
+create_abi_dump "$FROM"
+create_abi_dump "$TO"
+
+# Todo: Future iterations and extensions here could add "-stdout -xml" and
+# parse the results automatically
+abi-compliance-checker -l libcamera \
+	-old "$ABI_DIR/$FROM.abi.dump" \
+	-new "$ABI_DIR/$TO.abi.dump" \
+	;
+
+# On (far too many) occasions, the tools keep running leaving a cpu core @ 100%
+# CPU usage. Perhaps some subprocess gets launched but never rejoined. Stop
+# them all
+killall abi-compliance-checker 2>/dev/null
-- 
2.34.1