From: Dan Kegel <dank@kegel.com>
Date: Mon, 31 Aug 2020 16:37:40 +0000 (-0700)
Subject: test/abicheck.md: document care and feeding of abicheck.sh
X-Git-Tag: 1.9.9-b1~52
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=52d1278acbf9bfe391533db99572a4f5951b114a;p=thirdparty%2Fzlib-ng.git

test/abicheck.md: document care and feeding of abicheck.sh
---

diff --git a/test/abicheck.md b/test/abicheck.md
new file mode 100644
index 00000000..6e9e58aa
--- /dev/null
+++ b/test/abicheck.md
@@ -0,0 +1,59 @@
+ABI Compatibility test
+----------------------
+
+abicheck.sh uses libabigail to check ABI stability.
+It will abort if the current source
+tree has a change that breaks binary compatibility.
+
+This protects against the common scenario where:
+- an app is compiled against the current zlib-ng
+- the system package manager updates the zlib-ng shared library
+- the app now crashes because some symbol is
+  missing or some public structure or parameter
+  has changed type or size
+
+If run with --zlib-compat, it verifies that the
+current source tree generates a library that
+is ABI-compatible with the reference release
+of classic zlib.  This ensures that building
+zlib-ng with --zlib-compat does what it says on the tin.
+
+abicheck.sh is not perfect, but it can catch
+many common compatibility issues.
+
+Cached files test/abi/*.abi
+---------------------------
+
+Comparing to the old version of zlib (or zlib-ng)
+means someone has to check out and build
+the previous source tree and extract its .abi
+using abidw.  This can be slow.
+
+If you don't mind the slowness, run abicheck.sh --refresh_if,
+and it will download and build the reference version
+and extract the .abi on the spot if needed.
+(FIXME: should this be the default?)
+
+On the next run, the reference .abi file will already be
+present, and that step will be skipped.
+It's stored in the tests/abi directory,
+in a file with the architecture and git hash in the name.
+
+If you're running continuous integration
+which clear out the source tree on each run,
+and you don't want your build machines
+constantly downloading and building the old
+version, you can check the .abi file into git.
+
+To make this easier, a helper script could be written to automatically build
+all the configurations tested by .github/worflows/abicheck.yml
+Then they could be checked into git en masse by a maintainer
+when a new platform is added or a new major version (which
+intentionally breaks backwards compatibility) is being prepared.
+
+Further reading
+---------------
+
+- https://sourceware.org/libabigail/manual/
+- https://developers.redhat.com/blog/2014/10/23/comparing-abis-for-compatibility-with-libabigail-part-1/
+- https://developers.redhat.com/blog/2020/04/02/how-to-write-an-abi-compliance-checker-using-libabigail/