Never Mis-Bump a .so Version Again
TL;DR — I built a free interactive web-tool and also found an alternative, more human-friendly algorithm.
For every software release that involves a shared library
you have to consider bumping the -version-info C:R:A
part of your linker arguments
so that your libxyz.so.1.2.3
numbers match the semantic changes you did since the previous release.
Finding the correct new set of numbers can be a bit tricky. The current best place for how to bump them properly is probably section 7.3 Updating library version information of the GNU Libtool documentation. Ignoring the details, you'll be given this very structure:
- Start with version information of ‘0:0:0’ for each Libtool library.
- [..]
- If [..].
- If [..].
- If [..].
- If [..].
It took me a while to figure out what I'd need to do when multiple of those ifs apply: what they give you is an algorithm to follow step by step — it involves state and that state is carried from one step to the next.
While that algorithm is precise, it is a lot better suited to machines than humans. One reason is that — with multiple steps and state involved — there is quite some chance for the result to turn out wrong. Does it have to be that complicated?
In this post I would like to offer two things:
-
A simpler algorithm that doesn't involve state or pen and paper.
-
A web-tool to play with things interactively.
A Stateless Algorithm
So let's get rid of the overlapping ifs and state and move
to exclusive else if
instead.
The stateless algorithm is this:
-
If it's the first release ever go with
-version-info 0:0:0
. -
Else if you haven't made any changes to the source code but still need to do a re-release,
keep the version info untouched and re-use the same values. -
Else if you have made backwards-incompatible changes to the API — removed or changed something existing — bump applying
+1/=0/=0
:-version-info C:R:A
becomes-version-info <C+1>:0:0
. -
Else if you have only added to the public API and are sure of backwards compatibility bump applying
+1/=0/+1
:-version-info C:R:A
becomes-version-info <C+1>:0:<A+1>
. -
Else bump applying
+0/+1/+0
:-version-info C:R:A
becomes-version-info C:<R+1>:A
.
The Interactive Web-Tool
The small interactive web-tool I built is now online at https://verbump.de/ . If you like it, please support it by starring the GitHub repository. Thank you!
Enough version bumping for today.