1ABI Compatibility test
2----------------------
3
4abicheck.sh uses libabigail to check ABI stability.
5It will abort if the current source
6tree has a change that breaks binary compatibility.
7
8This protects against the common scenario where:
9- an app is compiled against the current zlib-ng
10- the system package manager updates the zlib-ng shared library
11- the app now crashes because some symbol is
12  missing or some public structure or parameter
13  has changed type or size
14
15If run with --zlib-compat, it verifies that the
16current source tree generates a library that
17is ABI-compatible with the reference release
18of classic zlib.  This ensures that building
19zlib-ng with --zlib-compat does what it says on the tin.
20
21abicheck.sh is not perfect, but it can catch
22many common compatibility issues.
23
24Cached files test/abi/*.abi
25---------------------------
26
27Comparing to the old version of zlib (or zlib-ng)
28means someone has to check out and build
29the previous source tree and extract its .abi
30using abidw.  This can be slow.
31
32If you don't mind the slowness, run abicheck.sh --refresh-if,
33and it will download and build the reference version
34and extract the .abi on the spot if needed.
35(FIXME: should this be the default?)
36
37On the next run, the reference .abi file will already be
38present, and that step will be skipped.
39It's stored in the tests/abi directory,
40in a file with the architecture and git hash in the name.
41
42If you're running continuous integration
43which clear out the source tree on each run,
44and you don't want your build machines
45constantly downloading and building the old
46version, you can check the .abi file into git.
47
48To make this easier, a helper script could be written to automatically build
49all the configurations tested by .github/workflows/abicheck.yml
50Then they could be checked into git en masse by a maintainer
51when a new platform is added or a new major version (which
52intentionally breaks backwards compatibility) is being prepared.
53
54Further reading
55---------------
56
57- https://sourceware.org/libabigail/manual/
58- https://developers.redhat.com/blog/2014/10/23/comparing-abis-for-compatibility-with-libabigail-part-1/
59- https://developers.redhat.com/blog/2020/04/02/how-to-write-an-abi-compliance-checker-using-libabigail/
60