Shared library (DLL) version numbering on Cygwin

msg id 3D3A042BDOT3070107ATeceDOTgatechDOTedu
sent to png-implementATccrcDOTwustlDOTedu
From: Charles Wilson cwilsonATeceDOTgatechDOTedu

A couple of definitions:

entry points are *externally accessible* functions or variables exported by the DLL. The interface is the set of all these exported functions and variables in a given version of the library.

Regarding the libPNG version macros in makefile.cygwin:

You ONLY need to bump PNGDLL if the new dll REMOVES an entry point that the old dll provided. If you ADD a new entry point, then the new dll is a drop-in replacement for the old one, since the new one provides everything the old one did.

Of course, an app compiled against the new version, which uses the additional entry points, won't work with the old dll — but nobody ever promised FORWARD compatibility, only BACKWARD compatibility.

1.     follow the libtool versioning scheme (extracted from here):
   • So, libtool library versions are described by three integers:

   • current

     The most recent interface number that this library implements.

     revision

     The implementation number of the current interface.

     age

     The difference between the newest and oldest interfaces that this library implements. In other words, the library implements all the interface numbers in the range from number current - age to current.

   Updating libtool versioning:

   •     
   1. Start with version information of 0:0:0 for each libtool library.
   2. Update the version information only immediately before a public release of your software. More frequent updates are unnecessary, and only guarantee that the current interface number gets larger faster.
   3. If the library source code has changed at all since the last update, then increment revision (c:r:a becomes c:r+1:a).
   4. If any interfaces have been added, removed, or changed since the last update, increment current, and set revision to 0.
   5. If any interfaces have been added since the last public release, then increment age.
   6. If any interfaces have been removed since the last public release, then set age to 0.

   Never try to set the interface numbers so that they correspond to the release number of your package. This is an abuse that only fosters misunderstanding of the purpose of library versions. Instead, use the -release flag (see Release numbers), but be warned that every release of your package will not be binary compatible with any other release.

   
   
2.      On windows/cygwin, the DLLVER is ' c - a ' (trust me, this is correct, but it's easier to explain by example).

So, here's an example: the libtool version is 5:4:3, which indicates revision 4 of the implementation of interface 5, which happens to be backwards compatible with the three previous interface definitions. (ie. it is safe for applications linked against interfaces 5, 4, 3 and 2 to load the 5:4:3 dll at runtime).

So, let's look at the likely history of the mystery dll. I am following the c:r:a update rules described above.

All of these DLLs with DLLVER = 2 (2:0:0, 3:0:1, 4:0:2, 5:0:3, 5:1:3, 5:2:3, 5:3:3, and 5:4:3) are all strictly backwards compatible: it is guaranteed that any newer DLL in the series can be loaded by an exe that was compiled against an older DLL in the series.

In 1.2.3, the DLLVER was 12. Let's pretend that was a 'c' - 'a' of 12, and that 'c' = 12 and 'a' = 0.

In [libpng] 1.2.4, you simply added some new functions — but did NOT remove any. So, the new libtool number is 13:0:1 — and DLLVER remains 12.