Commit cb4da344 for whisper.cpp
commit cb4da344da4ca22d6ceb597e7e0919ba7e2e9b5c
Author: Daniel Bevenius <daniel.bevenius@gmail.com>
Date: Thu Nov 19 11:50:03 2026 +0100
ci : add API/ABI check to make-release workflow (#4185)
* ci : add API/ABI check to make-release workflow
This commit adds an API/ABI compatibility check to the make-release
workflow similar to what we have in llama.cpp.
Refs: https://github.com/ggml-org/llama.cpp/pull/28947
* scripts : skip whisper/parakeet internal symbols in apiabi check
This commit excludes internal whisper.cpp/parakeet.cpp symbols from the
api/abi checks. We are only concerned about the API/ABI that whisper.cpp
and parakeet.cpp expose and not to internal changes in ggml.
The motivation for this change is that currently there are many
errors/warnings about ggml changes that are not exported which can make
it difficult to understand if what type of semver dump is required.
With the changes in this commit there are only two warnings that are
emitted from whisper.h. These are two anonymous structs, greedy and
beam_search, which are jus the the compiler giving them new internal
names. A future commit could consider giving these structs names and we
would then avoid them, but that would probably be considered a minor
bump so I'm leaving it out of this commit.
* scripts : enable dry-run for tag check
* scripts : print API problems to stdout
diff --git a/.github/workflows/make-release.yml b/.github/workflows/make-release.yml
index 451c3a51..24d9d36d 100644
--- a/.github/workflows/make-release.yml
+++ b/.github/workflows/make-release.yml
@@ -13,6 +13,16 @@ on:
required: true
type: boolean
default: true
+ skip_apiabi_check:
+ description: 'Skip API/ABI compatibility check'
+ required: false
+ type: boolean
+ default: false
+ apiabi_compare_tag:
+ description: 'Tag to compare against for API/ABI check (default: latest release)'
+ required: false
+ type: string
+ default: ''
env:
GH_TOKEN: ${{ github.token }}
@@ -32,12 +42,27 @@ jobs:
fetch-depth: 0
ssh-key: ${{ secrets.DEPLOY_KEY_RELEASE }}
+ - name: Install API/ABI check tools
+ if: ${{ github.event.inputs.skip_apiabi_check != 'true' }}
+ run: sudo apt-get install -y abi-compliance-checker abigail-tools
+
- name: Run release checks
id: checks
run: bash scripts/make-release-checks.sh ${{ github.event.inputs.dry_run == 'true' && '--dry-run' || '' }}
env:
GITHUB_REPOSITORY: ${{ github.repository }}
RELEASE_BRANCH: ${{ github.ref_name }}
+ SKIP_APIABI_CHECK: ${{ github.event.inputs.skip_apiabi_check }}
+ APIABI_COMPARE_TAG: ${{ github.event.inputs.apiabi_compare_tag }}
+ APIABI_REPORT_DIR: ${{ runner.temp }}/apiabi-reports
+
+ - name: Upload API/ABI reports
+ if: ${{ always() && github.event.inputs.skip_apiabi_check != 'true' }}
+ uses: actions/upload-artifact@v4
+ with:
+ name: apiabi-reports
+ path: ${{ runner.temp }}/apiabi-reports
+ if-no-files-found: ignore
- name: Create release tag
if: ${{ github.event.inputs.dry_run == 'false' }}
diff --git a/scripts/check-apiabi-compat.sh b/scripts/check-apiabi-compat.sh
new file mode 100755
index 00000000..09ce68b5
--- /dev/null
+++ b/scripts/check-apiabi-compat.sh
@@ -0,0 +1,330 @@
+#!/bin/sh
+# Check for backwards-incompatible API and ABI changes between two builds
+#
+# Backwards-incompatible API changes, such as removing a value from an enum,
+# are checked by abi-compliance-checker. Such changes can break compilation of
+# existing programs.
+#
+# Backwards-incompatible ABI changes, such as the removal of a public function,
+# are checked by libigail-tools. Such changes could break run-time dynamic
+# linking of existing binaries. (We don't use a-c-c for ABI checks because it
+# needs a debug build, whereas abigail does not.)
+#
+# Commands:
+# --generate <build-dir>: Creates API/ABI dumps in <build-dir>
+# <build-dir> is expected to be a CMake build result
+# --check <dir1> <dir2>: Compares dumps in <dir1> and <dir2>
+# Comparison exit codes
+# 0: all good
+# 1: backwards-incompatible changes found
+#
+# Options:
+# --include-path <dir>: a-c-c calls gcc on headers; use this option to add
+# directories to gcc's search path
+#
+#
+# This script would typically be used before cutting a release:
+#
+# 1. Generate API/ABI dump for the old version
+#
+# $ check-apiabi-compat.sh --generate <build-dir-old> libfoo [ libbar ...]
+#
+# 2. <update source>
+#
+# 3. Generate API/ABI dump for the new version
+#
+# $ check-apiabi-compat.sh --generate <build-dir-new> libfoo [ libbar ...]
+#
+# 4. Compare the two dumps
+#
+# $ check-apiabi-compat.sh --check <old-build-dir> <new-build-dir>
+#
+# If the check exits 0, all is fine. Otherwise, backwards-incompatible
+# changes were found, and the librar(ies) need a SOVER bump.
+set -eu
+
+# Preconditions
+if ! command -v abi-compliance-checker >/dev/null 2>&1; then
+ echo "abi-compliance-checker is not installed." >&2
+ exit 1
+elif ! command -v abidw >/dev/null 2>&1; then
+ echo "abigail-tools are not installed." >&2
+ exit 1
+fi
+
+# Some generic functions
+usage() {
+ echo "Usage: $0 [ --include-path <dir> ] --generate <build-dir> libXXX [ libYYY ... ]" >&2
+ echo " $0 [ --strict ] --check <old-build-dir> <new-build-dir>" >&2
+ echo "" >&2
+ echo " --strict: fail on any API/ABI change, including backwards-compatible additions" >&2
+}
+
+get_cmake_project_name() {
+ sed -nr 's/^project\("(.*)".*$/\1/p' CMakeLists.txt
+}
+
+get_cmake_version() {
+ major="$(sed -nr 's/^set\([A-Z]+_VERSION_MAJOR ([0-9]+)\)$/\1/p' CMakeLists.txt)"
+ minor="$(sed -nr 's/^set\([A-Z]+_VERSION_MINOR ([0-9]+)\)$/\1/p' CMakeLists.txt)"
+ patch="$(sed -nr 's/^set\([A-Z]+_VERSION_PATCH ([0-9]+)\)$/\1/p' CMakeLists.txt)"
+ echo "$major.$minor.$patch"
+}
+
+# Option parsing and validation
+DO_GEN=0
+DO_CHECK=0
+STRICT=0
+BUILD_DIR=
+BUILD_DIR_NEW=
+INCLUDE_PATHS=
+while [ "$#" -gt 0 ]; do
+ case "$1" in
+ --generate=*)
+ DO_GEN=1
+ BUILD_DIR="${1#*=}"
+ shift
+ ;;
+ --generate)
+ DO_GEN=1
+ if [ -z "${2:-}" ]; then
+ usage
+ exit 1
+ fi
+ BUILD_DIR="$2"
+ shift 2
+ ;;
+ --check)
+ DO_CHECK=1
+ if [ -z "${2:-}" ] || [ -z "${3:-}" ]; then
+ usage
+ exit 1
+ elif ! [ -d "$2" ]; then
+ echo "$2 is not a directory." >&2
+ exit 1
+ elif ! [ -d "$3" ]; then
+ echo "$3 is not a directory." >&2
+ exit 1
+ fi
+ BUILD_DIR="$2"
+ BUILD_DIR_NEW="$3"
+ shift 3
+ ;;
+ --include-path=*)
+ INCLUDE_PATHS="$INCLUDE_PATHS ${1#*=}"
+ shift
+ ;;
+ --include-path)
+ if [ -z "${2:-}" ]; then
+ usage
+ exit 1
+ fi
+ INCLUDE_PATHS="$INCLUDE_PATHS $2"
+ shift 2
+ ;;
+ --strict)
+ STRICT=1
+ shift
+ ;;
+ -h | --help)
+ usage
+ exit 1
+ ;;
+ -?*)
+ usage
+ exit 1
+ ;;
+ *)
+ break
+ ;;
+ esac
+done
+if [ $((DO_GEN + DO_CHECK)) -gt 1 ]; then
+ echo "Can only use one --command." >&2
+ exit
+fi
+PROJECT_NAME="$(get_cmake_project_name)"
+PROJECT_VERSION="$(get_cmake_version)"
+LIB_NAMES=""
+while [ "$#" -gt 0 ]; do
+ if [ "${1#lib}" = "$1" ]; then
+ echo "Library to check must start with libXXX." >&2
+ exit 1
+ fi
+ LIB_NAMES="$LIB_NAMES $1"
+ shift
+done
+
+dump_current_api() {
+ echo "Dumping API..."
+
+ DESCRIPTOR="$BUILD_DIR/apiabi/acc-descriptor.xml"
+ mkdir -p "$BUILD_DIR/apiabi"
+ cat >"$DESCRIPTOR" <<EOF
+<version>$PROJECT_VERSION</version>
+<headers>include</headers>
+<add_include_paths>$INCLUDE_PATHS</add_include_paths>
+EOF
+
+ # This addresses a bug between a-c-c and universal-ctags, manifested when
+ # a name is use both for a tag and a function name
+ mkdir -p "$BUILD_DIR/apiabi/.ctags.d"
+ echo "--fields=-t" >"$BUILD_DIR/apiabi/.ctags.d/acc.ctags"
+
+ # Change HOME so that .ctags.d gets picked up by universal-ctags, if used
+ HOME="$BUILD_DIR/apiabi" abi-compliance-checker \
+ -headers-only \
+ -lib "$PROJECT_NAME" \
+ -dump "$DESCRIPTOR" \
+ -log-path "$BUILD_DIR/apiabi/acc.log" \
+ -dump-path "$BUILD_DIR/apiabi/api.dump"
+ # acc generates this file with an ancient timestamp, which confuses gzip
+ touch "$BUILD_DIR/apiabi/api.dump"
+}
+
+dump_current_abi() {
+ echo "Dumping ABIs ..."
+ mkdir -p "$BUILD_DIR/apiabi"
+ # The suppressions are needed to avoid including all the internal C++
+ # symbols, and system types
+ cat >"$BUILD_DIR/apiabi/abidw.suppress" <<EOF
+[suppress_function]
+
+label = suppress internal C++ mangled functions
+symbol_name_regexp = ^_Z
+drop = yes
+
+[suppress_variable]
+label = suppress internal C++ mangled variables
+symbol_name_regexp = ^_Z
+drop = yes
+
+[suppress_type]
+label = Suppress types outside of our own source
+source_location_not_regexp = ^include/
+drop = yes
+EOF
+
+ # In abidw 2.5, handling of undefined stuff was changed a bit
+ abidw_version="$(abidw --version | sed -r 's/^abidw: ([0-9]+\.[0-9]+).*$/\1/')"
+ abidw_major="${abidw_version%.*}"
+ abidw_minor="${abidw_version#*.}"
+ if [ "$abidw_major" -gt 2 ] || [ "$abidw_minor" -gt 4 ]; then
+ abidw_undefined_syms_options="--no-load-undefined-interfaces"
+ else
+ abidw_undefined_syms_options="--drop-undefined-syms"
+ fi
+
+ for lib_name in $LIB_NAMES; do
+ # Depending on where add_library resides, the libraries can end up in
+ # build/src or build/bin
+ lib_path="$BUILD_DIR/src/$lib_name.so"
+ if ! [ -f "$lib_path" ]; then
+ lib_path="$BUILD_DIR/bin/$lib_name.so"
+ if ! [ -f "$lib_path" ]; then
+ echo "Cannot find library $lib_name.so" >&2
+ exit 1
+ fi
+ fi
+ abidw \
+ --headers-dir include \
+ "$abidw_undefined_syms_options" \
+ --suppressions "$BUILD_DIR/apiabi/abidw.suppress" \
+ --out-file "${BUILD_DIR}/apiabi/$lib_name.abi.xml" \
+ "$lib_path"
+ done
+}
+
+# Run the actual commands
+if [ "$DO_GEN" -eq 1 ]; then
+ dump_current_api
+ dump_current_abi
+ exit 0
+elif [ "$DO_CHECK" -eq 1 ]; then
+ # From here on, we don't want to exit on first error
+ set +e
+
+ ACC_STRICT=
+ [ "$STRICT" -eq 0 ] || ACC_STRICT="-strict"
+ # Included ggml headers contribute declarations to the API dumps. Check
+ # only our API entry points, retaining the dependency types they expose.
+ compare_api() {
+ abi-compliance-checker \
+ $ACC_STRICT \
+ -source \
+ -skip-internal-symbols '^(?!whisper_|parakeet_)' \
+ -library "$PROJECT_NAME" \
+ -old "$BUILD_DIR/apiabi/api.dump" \
+ -new "$BUILD_DIR_NEW/apiabi/api.dump" \
+ "$@"
+ }
+ compare_api -src-report-path "$BUILD_DIR_NEW/apiabi/api_compat_report.html"
+ API_RESULT=$?
+
+ # Keep the HTML report and use XML to print individual findings to the log.
+ if command -v python3 >/dev/null 2>&1; then
+ API_XML="$BUILD_DIR_NEW/apiabi/api_compat_report.xml"
+ compare_api -report-format xml -stdout >"$API_XML"
+ XML_RESULT=$?
+ if [ "$XML_RESULT" -le 1 ]; then
+ python3 - "$API_XML" <<'PY'
+import re
+import sys
+import xml.etree.ElementTree as ET
+
+root = ET.parse(sys.argv[1]).getroot()
+for section in root:
+ if section.tag in ("added_symbols", "removed_symbols"):
+ action = "Added" if section.tag == "added_symbols" else "Removed"
+ for symbol in section.findall("./header/library/name"):
+ print(f"[{action}] {symbol.text}\n")
+ elif section.tag.startswith("problems_with_") and section.get("severity") != "Safe":
+ for change in section.findall(".//problem/change"):
+ message = re.sub(r"@(\w+)", lambda m: change.get(m[1], m[0]), change.text or "")
+ print(f"[{section.get('severity')}] {message}\n")
+PY
+ if [ "$?" -ne 0 ]; then
+ echo "Warning: could not summarize API findings; see the HTML report." >&2
+ fi
+ else
+ echo "Warning: could not generate XML API report (exit $XML_RESULT)." >&2
+ fi
+ else
+ echo "Warning: python3 is not installed; API findings are in the HTML report." >&2
+ fi
+
+ ABI_RESULT=0
+ for xml_file in "$BUILD_DIR/apiabi/"lib*.abi.xml; do
+ xml_file_new="$BUILD_DIR_NEW/apiabi/$(basename "$xml_file")"
+
+ if ! [ -f "$xml_file_new" ]; then
+ echo "Cannot compare, missing file: $xml_file_new" >&2
+ exit 1
+ fi
+
+ abidiff "$xml_file" "$xml_file_new"
+ res=$?
+ [ "$((res & 8))" -ne 0 ] && ABI_RESULT=1
+ # check bit 2 for compatible ABI changes (like new symbols) and if
+ # STRICT is set then handle this as an error.
+ [ "$STRICT" -eq 1 ] && [ "$((res & 4))" -ne 0 ] && ABI_RESULT=1
+ done
+
+ if [ "$API_RESULT" -gt 0 ]; then
+ if [ "$STRICT" -eq 1 ]; then
+ echo "ERROR: API changed — a minor version bump is required." >&2
+ else
+ echo "ERROR: API changed with backwards-incompatible problems — a major version bump is required." >&2
+ fi
+ fi
+ if [ "$ABI_RESULT" -gt 0 ]; then
+ if [ "$STRICT" -eq 1 ]; then
+ echo "ERROR: ABI changed — a minor version bump is required." >&2
+ else
+ echo "ERROR: ABI changed with backwards-incompatible problems — a major version bump is required." >&2
+ fi
+ fi
+ if [ "$((API_RESULT + ABI_RESULT))" -gt 0 ]; then
+ exit 1
+ fi
+fi
diff --git a/scripts/check-release-apiabi.sh b/scripts/check-release-apiabi.sh
new file mode 100755
index 00000000..7ee6807e
--- /dev/null
+++ b/scripts/check-release-apiabi.sh
@@ -0,0 +1,128 @@
+#!/bin/bash
+# Check API/ABI compatibility between the previous release tag and current HEAD.
+#
+# Finds the most recent vX.Y.Z tag, checks it out in a temporary git worktree,
+# builds both versions with shared libs enabled, and uses check-apiabi-compat.sh
+# to compare the results.
+#
+# Exit codes:
+# 0: compatible, or check was skipped
+# 1: backwards-incompatible changes found, or build failed
+#
+# Options:
+# --tag <version>: compare against this tag instead of the latest release
+#
+# Environment:
+# SKIP_APIABI_CHECK: set to 1 or true to skip
+# APIABI_COMPARE_TAG: equivalent to --tag (used by CI)
+# APIABI_REPORT_DIR: preserve reports and dumps in this directory, even if the comparison fails
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+LIBS=(libwhisper libparakeet)
+
+usage() {
+ echo "Usage: $0 [--tag <version>]" >&2
+ echo " --tag <version> Compare against this release tag (default: latest)" >&2
+}
+
+COMPARE_TAG="${APIABI_COMPARE_TAG:-}"
+while [[ "$#" -gt 0 ]]; do
+ case "$1" in
+ --tag)
+ if [[ -z "${2:-}" ]]; then usage; exit 1; fi
+ COMPARE_TAG="$2"
+ shift 2
+ ;;
+ --tag=*)
+ COMPARE_TAG="${1#*=}"
+ shift
+ ;;
+ -h | --help)
+ usage; exit 0
+ ;;
+ *)
+ usage; exit 1
+ ;;
+ esac
+done
+
+if [[ "${SKIP_APIABI_CHECK:-}" == "1" || "${SKIP_APIABI_CHECK:-}" == "true" ]]; then
+ echo "SKIP_APIABI_CHECK is set - skipping API/ABI compatibility check"
+ exit 0
+fi
+
+if ! command -v abi-compliance-checker >/dev/null 2>&1 || ! command -v abidw >/dev/null 2>&1; then
+ echo "Warning: abi-compliance-checker or abigail-tools not installed - skipping API/ABI check"
+ exit 0
+fi
+
+if [[ -n "${COMPARE_TAG}" ]]; then
+ PREV_TAG="${COMPARE_TAG}"
+ if ! git -C "$REPO_ROOT" rev-parse --verify "${PREV_TAG}^{}" >/dev/null 2>&1; then
+ echo "Error: tag '${PREV_TAG}' not found in repository." >&2
+ exit 1
+ fi
+else
+ PREV_TAG=$(git -C "$REPO_ROOT" tag --sort=-v:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -n 1 || true)
+ if [[ -z "${PREV_TAG}" ]]; then
+ echo "Warning: no previous release tag found - skipping API/ABI check"
+ exit 0
+ fi
+fi
+OLD_VERSION="${PREV_TAG#v}"
+OLD_MAJOR="${OLD_VERSION%%.*}"
+OLD_MINOR="${OLD_VERSION#*.}"; OLD_MINOR="${OLD_MINOR%%.*}"
+
+NEW_MAJOR=$(grep "set(WHISPER_VERSION_MAJOR" "$REPO_ROOT/CMakeLists.txt" | sed 's/.*MAJOR \([0-9]*\).*/\1/')
+NEW_MINOR=$(grep "set(WHISPER_VERSION_MINOR" "$REPO_ROOT/CMakeLists.txt" | sed 's/.*MINOR \([0-9]*\).*/\1/')
+
+if [[ "$NEW_MAJOR" -gt "$OLD_MAJOR" ]]; then
+ echo "Major version increment ($OLD_MAJOR -> $NEW_MAJOR): API/ABI breaking changes are expected, skipping compatibility check."
+ exit 0
+fi
+
+CHECK_FLAGS=()
+if [[ "$NEW_MINOR" -eq "$OLD_MINOR" ]]; then
+ echo "Patch version bump detected: checking for any API/ABI changes (a minor bump is required if any are found)..."
+ CHECK_FLAGS+=(--strict)
+else
+ echo "Minor version bump detected: checking for backwards-incompatible API/ABI changes..."
+fi
+
+echo "Checking API/ABI compatibility against ${PREV_TAG}..."
+
+WORKTREE_DIR=$(mktemp -d)
+BUILD_OLD=$(mktemp -d)
+BUILD_NEW=$(mktemp -d)
+
+cleanup() {
+ git -C "$REPO_ROOT" worktree remove --force "$WORKTREE_DIR" 2>/dev/null || true
+ rm -rf "$WORKTREE_DIR" "$BUILD_OLD" "$BUILD_NEW"
+}
+trap cleanup EXIT
+
+git -C "$REPO_ROOT" worktree add "$WORKTREE_DIR" "$PREV_TAG"
+
+cmake -S "$WORKTREE_DIR" -B "$BUILD_OLD" -DBUILD_SHARED_LIBS=ON -DCMAKE_BUILD_TYPE=RelWithDebInfo
+cmake --build "$BUILD_OLD" --parallel "$(nproc)"
+
+cmake -S "$REPO_ROOT" -B "$BUILD_NEW" -DBUILD_SHARED_LIBS=ON -DCMAKE_BUILD_TYPE=RelWithDebInfo
+cmake --build "$BUILD_NEW" --parallel "$(nproc)"
+
+(cd "$WORKTREE_DIR" && "$SCRIPT_DIR/check-apiabi-compat.sh" --include-path ggml/include --generate "$BUILD_OLD" "${LIBS[@]}")
+(cd "$REPO_ROOT" && "$SCRIPT_DIR/check-apiabi-compat.sh" --include-path ggml/include --generate "$BUILD_NEW" "${LIBS[@]}")
+
+CHECK_RESULT=0
+(cd "$REPO_ROOT" && "$SCRIPT_DIR/check-apiabi-compat.sh" "${CHECK_FLAGS[@]}" --check "$BUILD_OLD" "$BUILD_NEW") || CHECK_RESULT=$?
+
+if [[ -n "${APIABI_REPORT_DIR:-}" ]]; then
+ mkdir -p "$APIABI_REPORT_DIR/old" "$APIABI_REPORT_DIR/new"
+ cp -R "$BUILD_OLD/apiabi/." "$APIABI_REPORT_DIR/old/"
+ cp -R "$BUILD_NEW/apiabi/." "$APIABI_REPORT_DIR/new/"
+ echo "API/ABI reports saved to $APIABI_REPORT_DIR"
+fi
+
+exit "$CHECK_RESULT"
diff --git a/scripts/make-release-checks.sh b/scripts/make-release-checks.sh
index 7d3543dc..f604fe74 100755
--- a/scripts/make-release-checks.sh
+++ b/scripts/make-release-checks.sh
@@ -66,10 +66,16 @@ fi
echo "Checking that tag ${VERSION} does not already exist..."
if git ls-remote --tags origin "${VERSION}" | grep -q "${VERSION}"; then
- echo "Error: tag ${VERSION} already exists on remote"
- exit 1
+ if [[ "$DRY_RUN" == "true" ]]; then
+ echo "Warning: tag ${VERSION} already exists on remote (dry run, continuing)."
+ CHECKS_PASSED=false
+ else
+ echo "Error: tag ${VERSION} already exists on remote"
+ exit 1
+ fi
+else
+ echo "Tag ${VERSION} does not exist on remote - OK"
fi
-echo "Tag ${VERSION} does not exist on remote - OK"
echo "Checking release.yml status for commit ${SHA}..."
if [[ -z "${GITHUB_REPOSITORY:-}" ]]; then
@@ -120,6 +126,23 @@ else
fi
fi
+echo "Checking API/ABI compatibility..."
+set +e
+bash "$SCRIPT_DIR/check-release-apiabi.sh"
+APIABI_RESULT=$?
+set -e
+if [[ $APIABI_RESULT -ne 0 ]]; then
+ if [[ "$DRY_RUN" == "true" ]]; then
+ echo "Warning: API/ABI check found backwards-incompatible changes (dry run, continuing)."
+ CHECKS_PASSED=false
+ else
+ echo "Error: API/ABI check found backwards-incompatible changes."
+ exit 1
+ fi
+else
+ echo "API/ABI compatibility check passed - OK"
+fi
+
if [[ -n "${GITHUB_OUTPUT:-}" ]]; then
echo "checks_passed=${CHECKS_PASSED}" >> "$GITHUB_OUTPUT"
fi