C++ Standard Library ABI

The C++ interface

C++ applications often dependent on specific language supportroutines, say for throwing exceptions, or catching exceptions, andperhaps also dependent on features in the C++ Standard Library.

The C++ Standard Library has many include files, types defined inthose include files, specific named functions, and other behavior. Thetext of these behaviors, as written in source include files, is calledthe Application Programing Interface, or API.

Furthermore, C++ source that is compiled into object files is transformed by the compiler: it arranges objects with specific alignment and in a particular layout, mangling names according to a well-defined algorithm, has specific arrangements for the support of virtual functions, etc. These details are defined as the compiler Application Binary Interface, or ABI. The GNU C++ compiler uses an industry-standard C++ ABI starting with version 3. Details can be found in the ABI specification.

The GNU C++ compiler, g++, has a compiler command line option to switch between various different C++ ABIs. This explicit version switch is the flag -fabi-version. In addition, some g++ command line options may change the ABI as a side-effect of use. Such flags include -fpack-struct and -fno-exceptions, but include others: see the complete list in the GCC manual under the heading Options for Code Generation Conventions.

The configure options used when building a specific libstdc++version may also impact the resulting library ABI. The availableconfigure options, and their impact on the library ABI, are documentedhere.

Putting all of these ideas together results in the C++ Standardlibrary ABI, which is the compilation of a given library API by agiven compiler ABI. In a nutshell:

library API + compiler ABI = library ABI

The library ABI is mostly of interest for end-users who have unresolved symbols and are linking dynamically to the C++ Standard library, and who thus must be careful to compile their application with a compiler that is compatible with the available C++ Standard library binary. In this case, compatible is defined with the equation above: given an application compiled with a given compiler ABI and library API, it will work correctly with a Standard C++ Library created with the same constraints.

To use a specific version of the C++ ABI, one must use a corresponding GNU C++ toolchain (Ie, g++ and libstdc++) that implements the C++ ABI in question.

Versioning

The C++ interface has evolved throughout the history of the GNUC++ toolchain. With each release, various details have been changed soas to give distinct versions to the C++ interface.

Goals of versioning

Extending existing, stable ABIs. Versioning gives subsequent stablereleases series libraries the ability to add new symbols and addfunctionality, all the while retaining backwards compatibility withthe previous releases in the series. Note: the reverse is not true. Itis not possible to take binaries linked with the latest version of arelease series (if symbols have been added) and expect the initialrelease of the series to remain link compatible.

Allows multiple, incompatible ABIs to coexist at the same time.