diff options
Diffstat (limited to 'libstdc++-v3/docs/html/abi.txt')
| -rw-r--r-- | libstdc++-v3/docs/html/abi.txt | 389 |
1 files changed, 389 insertions, 0 deletions
diff --git a/libstdc++-v3/docs/html/abi.txt b/libstdc++-v3/docs/html/abi.txt new file mode 100644 index 00000000000..73cb46c9c09 --- /dev/null +++ b/libstdc++-v3/docs/html/abi.txt @@ -0,0 +1,389 @@ + +2002-10-14 Benjamin Kosnik + +Description of the libstdc++ ABI. + +I. What is an ABI? What's covered? What's not? + +- scope of document, of use to system integrators. + +- What's the deal with C++? Why can't different compiler's object + files link with each other? Bug? Feature? + +- compilation includes and linked library binary must match up.. + +- shared library only, static is immutable. + +- What's an ABI? + +- library ABI, compiler ABI different issues, (but related) + +- GNU C++ does not have a compiler command line option to switch + between various different C++ ABIs. For instance, there is no way to + switch between the gcc-3.0.x ABI, gcc-3.1.x ABI, and the gcc-3.2.x + ABI during compilation. Other C++ compilers do allow this, and some + g++ command line options may change the ABI (-fno-exceptions, see + the complete list), but there is no version switch. Sorry. + + To use a specific C++ABI, one must use the corresponding GNU C++ + toolchain. + +- How can this complexity be managed? What does C++ versioning mean? + Because library and compiler changes often make binaries compiled + with one version of the GNU tools incompatible with binaries + compiled with other (either newer or older) versions of the same GNU + tools, specific techniques are used to make managing this complexity + easier. + + The following techniques are used: + + - Release versioning on the libgcc_s.so binary. + + It is versioned as follows: + gcc-3.0.0: libgcc_s.so.1 + gcc-3.0.1: libgcc_s.so.1 + gcc-3.0.2: libgcc_s.so.1 + gcc-3.0.3: libgcc_s.so.1 + gcc-3.0.4: libgcc_s.so.1 + gcc-3.1.0: libgcc_s.so.1 + gcc-3.1.1: libgcc_s.so.1 + gcc-3.2.0: libgcc_s.so.1 + + + - Release versioning on the libstdc++.so binary. + + It is versioned as follows: + gcc-3.0.0: libstdc++.so.3.0.0 + gcc-3.0.1: libstdc++.so.3.0.1 + gcc-3.0.2: libstdc++.so.3.0.2 + gcc-3.0.3: libstdc++.so.3.0.2 (Error, should be libstdc++.so.3.0.3) + gcc-3.0.4: libstdc++.so.3.0.4 + gcc-3.1.0: libstdc++.so.4.0.0 + gcc-3.1.1: libstdc++.so.4.0.1 + gcc-3.2.0: libstdc++.so.5.0.0 + + + - Symbol versioning on the libgcc_s.so binary. + + file: gcc/libgcc-std.ver + + It is versioned as follows: + gcc-3.0.0: GCC_3.0 + gcc-3.0.1: GCC_3.0 + gcc-3.0.2: GCC_3.0 + gcc-3.0.3: GCC_3.0 + gcc-3.0.4: GCC_3.0 + gcc-3.1.0: GCC_3.0 + gcc-3.1.1: GCC_3.0 + gcc-3.2.0: GCC_3.0 + + + - Symbol versioning on the libstdc++.so binary. + + It is versioned as follows: + gcc-3.0.0: (Error, unversioned) + gcc-3.0.1: (Error, unversioned) + gcc-3.0.2: (Error, unversioned) + gcc-3.0.3: (Error, unversioned) + gcc-3.0.4: (Error, unversioned) + gcc-3.1.0: GLIBCPP_3.1, CXXABI_1 + gcc-3.1.1: GLIBCPP_3.1, CXXABI_1 + gcc-3.2.0: GLIBCPP_3.2, CXXABI_1.2 + + file: libstdc++-v3/config/linker-map.gnu + + + - Incremental bumping of a compiler pre-defined macro, + __GXX_ABI_VERSION. This macro is defined as the version of the + compiler v3 ABI, with g++ 3.0.x being version 100. This macro will + be automatically defined whenever g++ is used (the curious can + test this by invoking g++ with the '-v' flag.) + + This macro is defined in the file "lang-specs.h" in the gcc/cp directory. + Later versions define it in "c-common.c" in the gcc directory. + + It is versioned as follows: + gcc-3.0.x: 100 + gcc-3.1.x: 100 (Error, should be 101) + gcc-3.2.x: 102 + + + - Incremental bumping of a library pre-defined macro, + __GLIBCPP__. This macro is defined as the date the library was + released, in compressed ISO date format, as an unsigned long. + + This macro is defined in the file "c++config" in the + "libstdc++-v3/include/bits" directory and is changed every night + by an automated script. + + It is versioned as follows: + gcc-3.0.0: 20010615 + gcc-3.0.1: 20010819 + gcc-3.0.2: 20011023 + gcc-3.0.3: 20011220 + gcc-3.0.4: 20020220 + gcc-3.1.0: 20020514 + gcc-3.1.1: 20020725 + gcc-3.2.0: 20020814 + + + - Incremental bumping of a library pre-defined macro, + _GLIBCPP_VERSION. This macro is defined as the released version of + the library, as a string literal. This is only implemented in + gcc-3.1.0 releases and higher. + + This macro is defined in the file "c++config" in the + "libstdc++-v3/include/bits" directory and is generated + automatically by autoconf as part of the configure-time generation + of config.h. + + It is versioned as follows: + gcc-3.0.0: "3.0.0" + gcc-3.0.1: "3.0.0" (Error, should be "3.0.1") + gcc-3.0.2: "3.0.0" (Error, should be "3.0.2") + gcc-3.0.3: "3.0.0" (Error, should be "3.0.3") + gcc-3.0.4: "3.0.0" (Error, should be "3.0.4") + gcc-3.1.0: "3.1.0" + gcc-3.1.1: "3.1.1" + gcc-3.2.0: "3.2" + + + - Matching each specific C++ compiler release to a specific set of + C++ include files. This is only implemented in gcc-3.1.1 releases + and higher. + + All C++ includes are installed in include/c++, then nest in a + directory hierarchy corresponding to the C++ compiler's released + version. This version corresponds to the variable "gcc_version" in + "libstdc++-v3/acinclude.m4," and more details can be found in that + file's macro GLIBCPP_CONFIGURE. + + C++ includes are versioned as follows: + gcc-3.0.0: include/g++-v3 + gcc-3.0.1: include/g++-v3 + gcc-3.0.2: include/g++-v3 + gcc-3.0.3: include/g++-v3 + gcc-3.0.4: include/g++-v3 + gcc-3.1.0: include/g++-v3 + gcc-3.1.1: include/c++/3.1.1 + gcc-3.2.0: include/c++/3.2 + + Taken together, these techniques can accurately specify interface + and implementation changes in the GNU C++ tools themselves. Used + properly, they allow both the GNU C++ tools implementation, and + programs using them, an evolving yet controlled development that + maintains backward compatibility. + +- Minimum environment that supports a versioned ABI: what's needed? A + supported dynamic linker, a GNU linker of sufficient vintage to + understand demangled C++ name globbing (ld), a shared executable + compiled with g++, and shared libraries (libgcc_s, libstdc++-v3) + compiled by a compiler (g++) with a compatible ABI. Phew. + + On top of all that, an additional constraint: libstdc++ did not + attempt to version symbols (or age gracefully, really) until version + 3.1.0. + + Most modern Linux and BSD versions, particularly ones using + gcc-3.1.x tools, will meet the requirements above. + +- What configure options impact symbol versioning? + + It turns out that most of the configure options that change default + behavior will impact the mangled names of exported symbols, and thus + impact versioning and compatibility. + + For more information on configure options, including ABI impacts, see: + http://gcc.gnu.org/onlinedocs/libstdc++/configopts.html + + There is one flag that explicitly deals with symbol versioning: + --enable-symvers. + + In particular, libstdc++-v3/acinclude.m4 has a macro called + GLIBCPP_ENABLE_SYMVERS that defaults to yes (or the argument passed + in via --enable-symvers=foo). At that point, the macro attempts to + make sure that all the requirement for symbol versioning are in + place. For more information, please consult acinclude.m4. + +- How can I tell if symbol versioning is, indeed, active? + + When the GNU C++ library is being built with symbol versioning on, + you should see the following at configure time for libstdc++-v3: + + checking versioning on shared library symbols... gnu + + If you don't see this line in the configure output, or if this line + appears but the last word is 'no', then you are out of luck. + + If the compiler is pre-installed, a quick way to test is to compile + the following (or any) simple C++ file: + +#include <iostream> + +int main() +{ std::cout << "hello" << std::endl; return 0; } + +%g++ hello.cc -o hello.out +%nm hello.out + +If you see symbols in the resulting output with "GLIBCPP_3.x" as part +of the name, then the executable is versioned. Here's an example: + + U _ZNSt8ios_base4InitC1Ev@@GLIBCPP_3.1 + + +II. Library ABI changes + +The following will cause the library major version number to +increase, say from "libstdc++.so.3.0.4" to "libstdc++.so.4.0.0". + +- (anything) changing in the gcc/g++ compiler ABI + +- (anything) changing size of an exported symbol + +- (anything) changing alignment of an exported symbol + +- (anything) changing the layout of an exported symbol + +- (anything) changing mangling on an exported symbol + +- (anything) deleting an exported symbol + +- (anything) changing the size, alignment, or layout of types + specified in the C++ standard. These may not necessarily be + instantiated or otherwise exported in the library binary, and + include all the required locale facets, as well as things like + std::basic_streambuf, et al. + +Note: adding an exported symbol, if it's in a new and dependent +interface name, is ok. + +The following will cause the library revision version number to +increase, say from "libstdc++.so.5.0.0" to "libstdc++.so.5.0.1". + +- any release of the gcc toolchain. + + +III. Versioning + +- include files + + - versioning headers with version, why necessary + (need to control member/non-member functions, add delete files) + +- shared library binaries + + - release versions + + - libtool versions + + - when does so version get a bump? what are the options? + + - how is the link map used? + + - in an non-abi breaking minor release, how are symbols added? + removed? + + - in an abi-breaking major release, what happens? symbol fall back + + +IV. Testing ABI changes + +Testing for GNU C++ ABI changes is composed of two distinct areas: +testing the C++ compiler (g++) for compiler changes, and testing the +C++ library (libstdc++) for library changes. + +Testing the C++ compiler ABI can be done various ways. + +One. +Intel ABI checker. More information can be obtained +<a href="http://developer.intel.com/software/products/opensource/">here.</a> + +Two. +The second is yet unreleased, but has been announced on the gcc +mailing list. It is yet unspecified if these tools will be freely +available, and able to be included in a GNU project. Please contact +Mark Mitchell (mark@codesourcery.com) for more details, and current +status. + +Three. +Involves using the vlad.consistency test framework. This has also been +discussed on the gcc mailing lists. + +Testing the C++ library ABI can also be done various ways. + +One. +(Brendan Kehoe, Jeff Law suggestion to run 'make check-c++' two ways, +one with a new compiler and an old library, and the other with an old +compiler and a new library, and look for testsuite regressions) + +Details on how to set this kind of test up can be found here: +http://gcc.gnu.org/ml/gcc/2002-08/msg00142.html + +Two. +Use the 'make check-abi' rule in the libstdc++-v3 Makefile. + +This is a proactive check the library ABI. Currently, exported symbol +names that are either weak or defined are checked against a last known +good baseline. Currently, this baseline is keyed off of 3.2.0 +binaries, as this was the last time the .so number was incremented. In +addition, all exported names are demangled, and the exported objects +are checked to make sure they are the same size as the same object in +the baseline. + +This dataset is insufficient, yet a start. Also needed is a +comprehensive check for all user-visible types part of the standard +library for sizeof() and alignof() changes. + +Verifying compatible layouts of objects is not even attempted. It +should be possible to use sizeof, alignof, and offsetof to compute +offsets for each structure and type in the standard library, saving to +another datafile. Then, compute this in a similar way for new +binaries, and look for differences. + +Another approach might be to use the -fdump-class-hierarchy flag to +get information. However, currently this approach gives insufficient +data for use in library testing, as class data members, their offsets, +and other detailed data is not displayed with this flag. +(See g++/7470 on how this was used to find bugs.) + +Perhaps there are other C++ ABI checkers. If so, please notify +us. We'd like to know about them! + + +V. Issues not directly addressed, and possible suggestions + +- what to do about multi-ABI systems (nathan scenario)? + + - compatibility libs + + --enable-version-specific-runtime-libs + + - Alexandre Oliva proposal to have extended name attributes, modify ld + + - directory-level versioning + +- wrapping C++ API's in "C" to use the C ABI. + + +V. References + +ABIcheck, a vague idea of checking ABI compatibility +http://abicheck.sourceforge.net/ + +C++ ABI reference +http://www.codesourcery.com/cxx-abi/ + +Intel ABI documentation +"Intel® Compilers for Linux* -Compatibility with the GNU Compilers" +(included in icc 6.0) + +Sun Solaris 2.9 docs +Linker and Libraries Guide (document 816-1386) +C++ Migration Guide (document 816-2459) +http://docs.sun.com/db/prod/solaris.9 +http://docs.sun.com/?p=/doc/816-1386&a=load + +Ulrich Drepper, "ELF Symbol Versioning" +http://people.redhat.com/drepper/symbol-versioning + |