I am creating Debian packages for a SNMP library in C++ which unfortunately does not properly set soname or versioning information in the makefile. It is unacceptable to ship a library in those conditions under Debian guidelines.
If you are a C programmer you don’t need to worry as binary-compatibility is usually not an issue in C as it lacks polymorphism.
If you are a C++ programmer and you don’t know what an ABI is and why binary compatibility matters, you must first read and understand what an API, an ABI and name mangling are.
Even if you already knew about ABI and name mangling, you probably don’t know about binary compatibility in shared objects (libraries). Don’t worry: ABI-compatibility is non-obvius and most C++ programmers don’t know a word about that.
The idea is quite simple: if you uncarefully change the API of your library you have also changed the ABI of your library and, most probably, due to name-mangling and virtual tables (needed to support polymorphism), the new version of the library is ABI-incompatible with the older version.
There are two kind of changes you can make: extend the API/ABI but leave it compatible with former versions, or extend the API/ABI and break binary-compatibility. There is very good information about what changes render your library binary-compatible and which don’t in the KDE wiki and in the Qt FAQ.
Once ABI compatibility is clear, the next question arises: how does my library state its binary compatibiliy? There are essentially two mechanisms for that: the Sun Solaris-specific mechanism (which is great, by the way) and sonames (used by most other Unices and Linux). There is plenty of information about sonames at the libtool manual and the Debian Libraries Packaging Guide and a good example at LinuxQuestions. For more information about the Solaris mechanism, read carefully the DSO howto by Ulrich Drepper (page 35, section 3.3: “ABI Versioning”).
Two important things you have to remember:
- If your library version is the same as your soname version, you have not understood a thing of what I said above
- If your library is stable, follow these guidelines.
In case you really want to keep ABI-compatibility for whatever reason (you are developing a very spreaded C++ library and the user might have a newer/older version already installed, you don’t want to update versions unless totally necessary, etc), take a look at the opaque pointer technique (AKA D-Pointer) invented by Trolltech.