Symbol Versioning

In general, this capability exists only on a few platforms, thus there is a need for configure magic so that it is used only on those targets where it is supported.

The central concept in symbol versioning is the so-called map file, which specifies the version node(s) exported symbols are labeled with. Also, the map file is used to hide local symbols.

Some relevant references:

• GNU ld manual

• ELF Symbol Versioning - Ulrich Depper

• How to Write Shared Libraries - Ulrich Drepper (see Chapter 3)

If one adds a new symbol to a library that should be exported, the new symbol should be mentioned in the map file and a new version node defined, e.g., if one adds a new symbols foo and bar to libgfortran for the next GCC release, the following should be added to the map file:

GFORTRAN_1.1 {
    global:
        foo;
        bar;
} GFORTRAN_1.0;

where GFORTRAN_1.0 is the version node of the current release, and GFORTRAN_1.1 is the version node of the next release where foo and bar are made available.

If one wants to change an existing interface, it is possible by using some asm trickery (from the ld manual referenced above):

__asm__(".symver original_foo,foo@");
__asm__(".symver old_foo,foo@VERS_1.1");
__asm__(".symver old_foo1,foo@VERS_1.2");
__asm__(".symver new_foo,foo@VERS_2.0");

In this example, foo@ represents the symbol foo bound to the unspecified base version of the symbol. The source file that contains this example would define 4 C functions: original_foo, old_foo, old_foo1, and new_foo.

In this case the map file must contain foo in VERS_1.1 and VERS_1.2 as well as in VERS_2.0.