Skip to main content

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:

  1. Start with version information of ‘0:0:0’ for each Libtool library.
  2. [..]
  3. If [..].
  4. If [..].
  5. If [..].
  6. 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!

For a clickable preview: verbump.de

Enough version bumping for today.