Library lacks symbol versions

[SDLBugzilla]

This bug report was migrated from our old Bugzilla tracker.

Reported in version: 2.0.6
Reported for operating system, platform: Linux, x86_64

Comments on the original bug report:

On 2018-01-10 15:43:41 +0000, Jan Engelhardt wrote:

In SDL 2.0.5, SDL_RenderSetIntegerScale was added, but neither the SONAME was changed, nor were symbol versions used to indicate that there is an ABI boundary. This means that package managers which scan ELF files for dependencies will not pick up the news, leading to a system where a program built with SDL-2.0.6 is installable on SDL 2.0.3 systems, but is unrunnable.

$ LD_BIND_NOW=1 chocolate-doom
chocolate-doom: symbol lookup error: chocolate-doom: undefined symbol: SDL_RenderSetIntegerScale

Please add symbol versions. Something like

/* sdl.sym */
SDL_2.0.0 {
global:
SDL_xxx;
SDL_yyy;
...;
local:
*;
};
SDL_2.0.5 {
global:
SDL_RenderSetIntegerScale;
} SDL_2.0.0;

and use with gcc -Wl,--version-script=sdl.sym during build.

[icculus]

Thanks to build-scripts/fnsince.pl, we could actually do this now if we want to.

Putting in 2.0.20 milestone (but not committing to actually fixing this yet).

[slouken]

@smcv, what changes are needed to switch to versioned symbols? Is this a reasonable change to make without a major version bump?

[smcv]

Yes, I had meant to open an issue about this.

It's OK to add symbol versioning without a major version bump, because it is a backwards-compatible change. However, it is not a forwards-compatible change: any program or dependent library compiled against the new SDL will need a version that has versioned symbols, even if all the symbols it uses already existed in old versions of SDL.

Similarly, if we want SDL-built-by-CMake and SDL-built-by-Autotools to be drop-in replacements for each other, then versioned symbols need to be enabled at the same time and on the same platforms for both build systems. My suggestion would be to enable versioned symbols on GNU/Linux (Linux with glibc) unconditionally, and not enable them on other platforms; and if other platforms want to join in, they can send patches.

There are two different levels of symbol versioning we could have.

Single version-definition (basic versioned symbols), for library coexistence

A basic form of ELF symbol versioning avoids some bugs that can happen when two SONAMEs of the same library collide, and the recursive dependency tree of an executable pulls in both the old SONAME and the new SONAME. This isn't generally a problem on Windows, because Windows symbol resolution is a tree, but it can be a problem on Linux (and other ELF platforms) because ELF symbol resolution usually happens in a single flat global namespace, in which a symbol can "interpose" in front of a symbol of the same name. Interposing is necessary to make LD_PRELOAD work, but often undesirable.

The simplest form of symbol versioning is to put the same version (often the same string as the SONAME) on every public symbol. Linux distributions often prefer libraries to add at least this basic level of versioned symbols before breaking ABI, so that if the old and new versions both end up in the same process's address space, they won't fight. For instance, it's OK for both libpng16.so.16 and libpng12.so.0 to end up indirectly linked into the same process, because their symbols are tagged with PNG16_0 and PNG12_0 respectively. libdbus has a similar setup.

The easiest way to do this with a recent-ish binutils is to link with -Wl,--default-symver, which uses the SONAME of the library as the name of the version definition (verdef). That results in function names like SDL_GameControllerName@libSDL2-2.0.so.0 which won't collide with a potential future SDL_GameControllerName@libSDL3.so.0 in a potential future SDL 3. A real example of this: https://gitlab.gnome.org/GNOME/json-glib/-/merge_requests/28

Multiple version-definition (complex versioned symbols), for version-tracking

The more complex form that was requested by the original reporter of this issue involves keeping track of which version of the library added each symbol, with a new version definition (verdef) for each release that added new ABI, so that you can objdump a compiled binary and take a fairly good guess at what is the minimum version it needs. The libraries shipped by util-linux are a prominent example of this. libostree is another good example. json-c/json-c#639 is an example of a MR that added this to an existing library.

Some people are big fans of this, but despite being a distro library maintainer (one of the very people this is meant to benefit), I personally don't think this is all that good a tradeoff: it's a nice-to-have, but the amount of work that has to be done upstream is significant.

If you're going this way, then it is invalid (a bug) to have symbols that conditionally exist under some but not all build configurations, even more than with no versioned symbols or with the simpler form.

Possible transitions

These transitions are valid:

• Go from no versioned symbols to versioned symbols -> OK
• Go from simple versioned symbols to complex versioned symbols -> OK if you're careful, but the simple verdef must continue to be used for old symbols, with the more specific verdef only used for new symbols (otherwise it's an incompatible ABI break)

These transitions are invalid:

• Go from versioned symbols to no versioned symbols -> incompatible ABI break
• Go from versioned to differently versioned on the same symbol -> incompatible ABI break
  • As a result, go from complex versioned symbols to simple versioned symbols -> incompatible ABI break

[slouken]

If you simply use the SONAME for all functions, then don't you have to provide a symbol with each SONAME where it's valid? Or does the linker automatically use newer versions of the function if an application references the symbol with an older SONAME version?

[smcv]

There's only one SONAME for each compatible family of versions of the library: it's something like libSDL2-2.0.so.0, not libSDL2-2.0.so.0.18.2.

$ objdump -T -x /usr/lib/x86_64-linux-gnu/libSDL2-2.0.so.0.18.2
...
Dynamic Section:
...
  SONAME               libSDL2-2.0.so.0

The SONAME only changes when the library breaks backwards compatibility, for instance 1.2.x were libSDL-1.2.so.0, and SDL 3 might be libSDL3.so.0 or something.

[slouken]

Okay, so in our case the SONAME would be libSDL2-2.0.so.0 indefinitely, which is not helpful for anyone trying to do useful symbol versioning, correct?

[smcv]

The SONAME is libSDL2-2.0.so.0 until the ABI breaks (presumably SDL 3), at which point it changes. That means the simple form of symbol versioning is good for resolving collisions between SDL 2 and SDL 3 (which does have value!), but you're right that it doesn't help a library user to determine what minimal version of SDL their binary needs.

[slouken]

There shouldn't be any collisions between SDL 2 and SDL 3, as they'll have different major versions and applications linked to one won't run if that library version isn't present.

It sounds like the original poster was asking for individual symbol versions.

@icculus, is this something we want to add now that we have the perl script with information on symbol versions?