Proper library version numbering

[Joshua Root]

On 2015-5-2 23:30 , Lawrence Velázquez wrote:
> On May 2, 2015, at 9:05 AM, Ryan Schmidt <ryandesign at macports.org> wrote:
> 
>> But it's not totally clear to me what proper library versioning entails -- what specifically I should be telling the developers of those projects to do instead. There are too many different version numbers. For example:
>>
>>
>> $ port installed gettext
>> The following ports are currently installed:
>>  gettext @0.19.4_0+universal (active)
>>
>> $ otool -L /opt/local/lib/libintl.dylib 
>> /opt/local/lib/libintl.dylib:
>> 	/opt/local/lib/libintl.8.dylib (compatibility version 10.0.0, current version 10.3.0)
>> 	/opt/local/lib/libiconv.2.dylib (compatibility version 8.0.0, current version 8.1.0)
>> 	/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1213.0.0)
>> 	/System/Library/Frameworks/CoreFoundation.framework/Versions/A/CoreFoundation (compatibility version 150.0.0, current version 1151.16.0)
>>
>>
>> Assuming gettext is an example of proper library version numbering, what's the relationship between version "0.19.4" and version "8" and version "10.3.0"? What do each of those numbers represent? What would be the appropriate circumstances when a developer would change each of those numbers?
> 
> https://developer.apple.com/library/mac/documentation/DeveloperTools/Conceptual/DynamicLibraries/100-Articles/DynamicLibraryDesignGuidelines.html#//apple_ref/doc/uid/TP40002013-SW23
> 
> vq

tl;dr version:

Increase current_version when the library changes in any way.

Increase compatibility_version when new symbols are added.

Increase the major version (AKA "soname") when any symbols are removed
or have their semantics changed.

- Josh