Skip to content

Calamares ABI Checking

Sunday, 7 July 2024 | Adriaan de Groot

Seems like over 3 years ago I wrote something about ABI stability checking and investigated a little how tools could be used to help maintain ABI stability for Calamares. Here are some callback notes.

Tooling Choices

I ended up using abigail for ABI checking, because it’s available on FreeBSD and Ubuntu and just seems like it has a compatible mindset for what I want to do: tell me the ABI difference between two Calamares releases.

The tool for that is abidiff and applying the tool is literally a matter of getting two versions of a shared object (.so) and running diff.

In Calamares I put together some scripts to automate this, since building versions of the Calamares shared objects is not quite trivial. The scripts also help out with the ABI-stability promise (or, um .. pinky swear, maybe).

Calamares ABI Stability Policy

When the Calamares 3.3 series started, one of the ideas was that in 3.3, the ABI should be stable, so that external / third party modules for Calamares should be able to keep working without a recompile. During 3.2 development, things were very unstable and everything needed to be recompiled all the time – and having a Boost dependency didn’t help much either, since there are so many distro’s with poor .so hygiene.

So the idea was to keep ABI stability, and to check that it was so.

Unfortunately, 3.3.0 released with a wide-open ABI because I forgot to turn on hidden-visibility by default, and there were a lot of not-quite-there cleanups that still needed doing.

By the time 3.3.3 came out, three months later, things were in better shape.

Right now, I’ve defined 3.3.3 as “the stable starting point”, and check ABI compatibility against that every now-and-again. Not regularly, not as part of releases (I suppose I would accept a PR that added a check that enforces it as part of the release script).

Anyway, the idea is that there should be “minimal” ABI changes. That is a lot less strict than, say, the KDE Frameworks Policies about C++ compatibility (hm .. those pages talk a lot more about kdelibs and KDE4 than I would have expected). New classes are ok, and it’s also ok for them to take a couple of releases before “settling down”.

Calamares Current ABI Issues

Abigail is fairly verbose and quite explicit about changes; I like that. Here’s the summary of summary information between 3.3.3 and 3.3.9 (not released yet, development branch):

Changed leaf types summary: 1 leaf type changed
Removed/Changed/Added functions summary: 0 Removed, 2 Changed, 8 Added functions
Removed/Changed/Added variables summary: 0 Removed, 0 Changed, 1 Added variable
Function symbols changes summary: 0 Removed, 4 Added function symbols not referenced by debug info
Variable symbols changes summary: 0 Removed, 3 Added variable symbols not referenced by debug info

Added isn’t a problem (there was an issue where the PC would suspend / sleep during installation if you didn’t prod the mouse, and I added a class to manage sleep-inhibition through the XDG DBus API). Changed ones are more serious:

'struct Calamares::CommandLine at CommandList.h:31:1' changed:
  type size changed from 128 to 256 (in bits)
  2 data member insertions:
    'std::__1::chrono::seconds m_timeout', at offset 128 (in bits) at CommandList.h:101:1
    'std::__1::optional<bool> m_verbose', at offset 192 (in bits) at CommandList.h:102:1

I’ve decided that this class is sufficiently “internal-ish” and sufficiently new that I’m not going to worry about it – independent of the question whether anyone even builds external C++ modules for Calamares that use it.

Calamares Big ABI Changes

Just for the record, there’s nothing planned. I can imagine one or two things that would drive a big ABI upheaval: one is adding a virtual function to modules to help with consistent configuration loading – so that we can get better checking up-front of what distro’s are putting into the configuration files, rather than waiting for an installation to be botched.