Skip to content

Commit dfe4516

Browse files
authored
scripts: Add script to verify API/ABI compatibility (ggml-org#28579)
1 parent b29c606 commit dfe4516

1 file changed

Lines changed: 272 additions & 0 deletions

File tree

‎scripts/check-apiabi-compat.sh‎

Lines changed: 272 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,272 @@
1+
#!/bin/sh
2+
# Check for backwards-incompatible API and ABI changes between two builds
3+
#
4+
# Backwards-incompatible API changes, such as removing a value from an enum,
5+
# are checked by abi-compliance-checker. Such changes can break compilation of
6+
# existing programs.
7+
#
8+
# Backwards-incompatible ABI changes, such as the removal of a public function,
9+
# are checked by libigail-tools. Such changes could break run-time dynamic
10+
# linking of existing binaries. (We don't use a-c-c for ABI checks because it
11+
# needs a debug build, whereas abigail does not.)
12+
#
13+
# Commands:
14+
# --generate <build-dir>: Creates API/ABI dumps in <build-dir>
15+
# <build-dir> is expected to be a CMake build result
16+
# --check <dir1> <dir2>: Compares dumps in <dir1> and <dir2>
17+
# Comparison exit codes
18+
# 0: all good
19+
# 1: backwards-incompatible changes found
20+
#
21+
# Options:
22+
# --include-path <dir>: a-c-c calls gcc on headers; use this option to add
23+
# directories to gcc's search path
24+
#
25+
#
26+
# This script would typically be used before cutting a release:
27+
#
28+
# 1. Generate API/ABI dump for the old version
29+
#
30+
# $ check-apiabi-compat.sh --generate <build-dir-old> libfoo [ libbar ...]
31+
#
32+
# 2. <update source>
33+
#
34+
# 3. Generate API/ABI dump for the new version
35+
#
36+
# $ check-apiabi-compat.sh --generate <build-dir-new> libfoo [ libbar ...]
37+
#
38+
# 4. Compare the two dumps
39+
#
40+
# $ check-apiabi-compat.sh --check <old-build-dir> <new-build-dir>
41+
#
42+
# If the check exits 0, all is fine. Otherwise, backwards-incompatible
43+
# changes were found, and the librar(ies) need a SOVER bump.
44+
set -eu
45+
46+
# Preconditions
47+
if ! command -v abi-compliance-checker >/dev/null 2>&1; then
48+
echo "abi-compliance-checker is not installed." >&2
49+
exit 1
50+
elif ! command -v abidw >/dev/null 2>&1; then
51+
echo "abigail-tools are not installed." >&2
52+
exit 1
53+
fi
54+
55+
# Some generic functions
56+
usage() {
57+
echo "Usage: $0 [ --include-path <dir> ] --generate <build-dir> libXXX [ libYYY ... ]" >&2
58+
echo " $0 --check <old-build-dir> <new-build-dir>" >&2
59+
}
60+
61+
get_cmake_project_name() {
62+
sed -nr 's/^project\("(.*)".*$/\1/p' CMakeLists.txt
63+
}
64+
65+
get_cmake_version() {
66+
major="$(sed -nr 's/^set\([A-Z]+_VERSION_MAJOR ([0-9]+)\)$/\1/p' CMakeLists.txt)"
67+
minor="$(sed -nr 's/^set\([A-Z]+_VERSION_MINOR ([0-9]+)\)$/\1/p' CMakeLists.txt)"
68+
patch="$(sed -nr 's/^set\([A-Z]+_VERSION_PATCH ([0-9]+)\)$/\1/p' CMakeLists.txt)"
69+
echo "$major.$minor.$patch"
70+
}
71+
72+
# Option parsing and validation
73+
DO_GEN=0
74+
DO_CHECK=0
75+
BUILD_DIR=
76+
BUILD_DIR_NEW=
77+
INCLUDE_PATHS=
78+
while [ "$#" -gt 0 ]; do
79+
case "$1" in
80+
--generate=*)
81+
DO_GEN=1
82+
BUILD_DIR="${1#*=}"
83+
shift
84+
;;
85+
--generate)
86+
DO_GEN=1
87+
if [ -z "${2:-}" ]; then
88+
usage
89+
exit 1
90+
fi
91+
BUILD_DIR="$2"
92+
shift 2
93+
;;
94+
--check)
95+
DO_CHECK=1
96+
if [ -z "${2:-}" ] || [ -z "${3:-}" ]; then
97+
usage
98+
exit 1
99+
elif ! [ -d "$2" ]; then
100+
echo "$2 is not a directory." >&2
101+
exit 1
102+
elif ! [ -d "$3" ]; then
103+
echo "$3 is not a directory." >&2
104+
exit 1
105+
fi
106+
BUILD_DIR="$2"
107+
BUILD_DIR_NEW="$3"
108+
shift 3
109+
;;
110+
--include-path=*)
111+
INCLUDE_PATHS="$INCLUDE_PATHS ${1#*=}"
112+
shift
113+
;;
114+
--include-path)
115+
if [ -z "${2:-}" ]; then
116+
usage
117+
exit 1
118+
fi
119+
INCLUDE_PATHS="$INCLUDE_PATHS $2"
120+
shift 2
121+
;;
122+
-h | --help)
123+
usage
124+
exit 1
125+
;;
126+
-?*)
127+
usage
128+
exit 1
129+
;;
130+
*)
131+
break
132+
;;
133+
esac
134+
done
135+
if [ $((DO_GEN + DO_CHECK)) -gt 1 ]; then
136+
echo "Can only use one --command." >&2
137+
exit
138+
fi
139+
PROJECT_NAME="$(get_cmake_project_name)"
140+
PROJECT_VERSION="$(get_cmake_version)"
141+
LIB_NAMES=""
142+
while [ "$#" -gt 0 ]; do
143+
if [ "${1#lib}" = "$1" ]; then
144+
echo "Library to check must start with libXXX." >&2
145+
exit 1
146+
fi
147+
LIB_NAMES="$LIB_NAMES $1"
148+
shift
149+
done
150+
151+
dump_current_api() {
152+
echo "Dumping API..."
153+
154+
DESCRIPTOR="$BUILD_DIR/apiabi/acc-descriptor.xml"
155+
mkdir -p "$BUILD_DIR/apiabi"
156+
cat >"$DESCRIPTOR" <<EOF
157+
<version>$PROJECT_VERSION</version>
158+
<headers>include</headers>
159+
<add_include_paths>$INCLUDE_PATHS</add_include_paths>
160+
EOF
161+
162+
# This addresses a bug between a-c-c and universal-ctags, manifested when
163+
# a name is use both for a tag and a function name
164+
mkdir -p "$BUILD_DIR/apiabi/.ctags.d"
165+
echo "--fields=-t" >"$BUILD_DIR/apiabi/.ctags.d/acc.ctags"
166+
167+
# Change HOME so that .ctags.d gets picked up by universal-ctags, if used
168+
HOME="$BUILD_DIR/apiabi" abi-compliance-checker \
169+
-headers-only \
170+
-lib "$PROJECT_NAME" \
171+
-dump "$DESCRIPTOR" \
172+
-log-path "$BUILD_DIR/apiabi/acc.log" \
173+
-dump-path "$BUILD_DIR/apiabi/api.dump"
174+
# acc generates this file with an ancient timestamp, which confuses gzip
175+
touch "$BUILD_DIR/apiabi/api.dump"
176+
}
177+
178+
dump_current_abi() {
179+
echo "Dumping ABIs ..."
180+
mkdir -p "$BUILD_DIR/apiabi"
181+
# The suppressions are needed to avoid including all the internal C++
182+
# symbols, and system types
183+
cat >"$BUILD_DIR/apiabi/abidw.suppress" <<EOF
184+
[suppress_function]
185+
186+
label = suppress internal C++ mangled functions
187+
symbol_name_regexp = ^_Z
188+
drop = yes
189+
190+
[suppress_variable]
191+
label = suppress internal C++ mangled variables
192+
symbol_name_regexp = ^_Z
193+
drop = yes
194+
195+
[suppress_type]
196+
label = Suppress types outside of our own source
197+
source_location_not_regexp = ^include/
198+
drop = yes
199+
EOF
200+
201+
# In abidw 2.5, handling of undefined stuff was changed a bit
202+
abidw_version="$(abidw --version | sed -r 's/^abidw: ([0-9]+\.[0-9]+).*$/\1/')"
203+
abidw_major="${abidw_version%.*}"
204+
abidw_minor="${abidw_version#*.}"
205+
if [ "$abidw_major" -gt 2 ] || [ "$abidw_minor" -gt 4 ]; then
206+
abidw_undefined_syms_options="--no-load-undefined-interfaces"
207+
else
208+
abidw_undefined_syms_options="--drop-undefined-syms"
209+
fi
210+
211+
for lib_name in $LIB_NAMES; do
212+
# Depending on where add_library resides, the libraries can end up in
213+
# build/src or build/bin
214+
lib_path="$BUILD_DIR/src/$lib_name.so"
215+
if ! [ -f "$lib_path" ]; then
216+
lib_path="$BUILD_DIR/bin/$lib_name.so"
217+
if ! [ -f "$lib_path" ]; then
218+
echo "Cannot find library $lib_name.so" >&2
219+
exit 1
220+
fi
221+
fi
222+
abidw \
223+
--headers-dir include \
224+
"$abidw_undefined_syms_options" \
225+
--suppressions "$BUILD_DIR/apiabi/abidw.suppress" \
226+
--out-file "${BUILD_DIR}/apiabi/$lib_name.abi.xml" \
227+
"$lib_path"
228+
done
229+
}
230+
231+
# Run the actual commands
232+
if [ "$DO_GEN" -eq 1 ]; then
233+
dump_current_api
234+
dump_current_abi
235+
exit 0
236+
elif [ "$DO_CHECK" -eq 1 ]; then
237+
# From here on, we don't want to exit on first error
238+
set +e
239+
240+
abi-compliance-checker \
241+
-strict \
242+
-source \
243+
-library "$PROJECT_NAME" \
244+
-old "$BUILD_DIR/apiabi/api.dump" \
245+
-new "$BUILD_DIR_NEW/apiabi/api.dump" \
246+
-src-report-path "$BUILD_DIR_NEW/apiabi/api_compat_report.html"
247+
API_RESULT=$?
248+
249+
ABI_RESULT=0
250+
for xml_file in "$BUILD_DIR/apiabi/"lib*.abi.xml; do
251+
xml_file_new="$BUILD_DIR_NEW/apiabi/$(basename "$xml_file")"
252+
253+
if ! [ -f "$xml_file_new" ]; then
254+
echo "Cannot compare, missing file: $xml_file_new" >&2
255+
exit 1
256+
fi
257+
258+
abidiff "$xml_file" "$xml_file_new"
259+
res=$?
260+
[ "$((res & 8))" -ne 0 ] && ABI_RESULT=1
261+
done
262+
263+
if [ "$API_RESULT" -gt 0 ]; then
264+
echo "ERROR: API changed with possible backwards-compatibility problems." >&2
265+
fi
266+
if [ "$ABI_RESULT" -gt 0 ]; then
267+
echo "ERROR: ABI changed with possible backwards-compatibility problems." >&2
268+
fi
269+
if [ "$((API_RESULT + ABI_RESULT))" -gt 0 ]; then
270+
exit 1
271+
fi
272+
fi

0 commit comments

Comments
 (0)