3

I'm the author of a C++ library that is being distributed in multiple Linux packaging distributions. The library includes headers and source; Linux packages distribute it as headers + shared library (.so).

I'm looking for guidelines that would make the life of Linux package maintainers easier.

Things I'm interested in include:

  • API compatibility (e.g. changing function signatures). Obviously maintaining compatibility across minor releases is crucial. What about major version changes?

  • Binary compatibility (e.g. changing sizes of externally visible data structures). How important is it to be ABI-compatible across minor releases? Are there any issues with breaking that in major releases?

  • Build versioning advice. I'm currently using CMake - any specific settings that I should set to maximize the chance that package maintainers can just use my CMakeLists.txt?

If there is anything else that I'm missing I'd be glad to hear about it as well.

zeuxcg
  • 9,216
  • 1
  • 26
  • 33
  • Is it free software? If yes, you might leave the burden of packaging it to distribution packagers ... – Basile Starynkevitch Apr 16 '15 at 15:18
  • how do you plan to package it? debian, redhat and slackware, for example, use different package mechanisms (incompatible) ? – Luis Colorado Apr 17 '15 at 11:10
  • @BasileStarynkevitch It's MIT licensed. I'm not packaging it myself - but my question is precisely about that - how to make distribution packagers' life easier – zeuxcg Apr 17 '15 at 18:56
  • @LuisColorado I'm not packaging it myself - different people package it for different distributions – zeuxcg Apr 17 '15 at 18:56

2 Answers2

2

Let me tackle the ABI part. It depends a lot on if you will provide a pre-built binary that will work everywhere, or if you are relying on distributors to build it for you.

Consider Debian: once a package is in Debian, the build hosts recompile every update on every supported platform. The C ABI rarely changes but the C++ ABI requires special attention (as mentioned in this 2005 message to debian developers: http://lwn.net/Articles/139810/)

I don't think its reasonable to provide a C++ package that will work everywhere. ABI is too site-specific: https://gcc.gnu.org/onlinedocs/libstdc++/manual/abi.html

Rob Latham
  • 5,085
  • 3
  • 27
  • 44
  • Library is distributed in headers+source form; package maintainers build it. I'm more referring to the library-controlled ABI parts - e.g. changing the size of the class. – zeuxcg Apr 16 '15 at 15:10
  • The information about Debian is interesting! So for Debian only source compatibility matters and there is no burden in breaking ABI at the library level? – zeuxcg Apr 16 '15 at 15:11
2

As a Linux maintainer I can say that both backward binary (ABI) and source (API) compatibility of your library is very important for us.

API changes may break rebuild of some applications (or other libraries) in the distribution that depend on your library. This may break mass-rebuild of the distribution.

ABI changes may break particular binary updates. We need to verify ABI changes in updated libraries and rebuild all dependent applications if some dangerous changes are detected. In this case the user should download the update package for the library and for all dependent applications too. If library is backward API and ABI stable then we can update the library package only.

If you break ABI then please change SONAME of your library (bump version). And please do not introduce API/ABI changes in micro/patch releases.

I recommend you to use the abi-compliance-checker tool to verify your library for API/ABI backward compatibility. See sample reports of the tool for the Qt library: http://abi-laboratory.pro/tracker/timeline/qt/

You need to compile debug version of your library with addition -g -Og options and dump ABI of your library with the help of the abi-dumper tool. And then compare two ABI dumps of different versions to generate ABI changes report.

enter image description here

linuxbuild
  • 15,843
  • 6
  • 60
  • 87