diff options
Diffstat (limited to 'neozip/test/abicheck.md')
| -rw-r--r-- | neozip/test/abicheck.md | 59 |
1 files changed, 59 insertions, 0 deletions
diff --git a/neozip/test/abicheck.md b/neozip/test/abicheck.md new file mode 100644 index 0000000000..57337f5882 --- /dev/null +++ b/neozip/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/workflows/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/ |