From 554fd8c5195424bdbcabf5de30fdc183aba391bd Mon Sep 17 00:00:00 2001 From: upstream source tree Date: Sun, 15 Mar 2015 20:14:05 -0400 Subject: obtained gcc-4.6.4.tar.bz2 from upstream website; verified gcc-4.6.4.tar.bz2.sig; imported gcc-4.6.4 source tree from verified upstream tarball. downloading a git-generated archive based on the 'upstream' tag should provide you with a source tree that is binary identical to the one extracted from the above tarball. if you have obtained the source via the command 'git clone', however, do note that line-endings of files in your working directory might differ from line-endings of the respective files in the upstream repository. --- libstdc++-v3/doc/xml/manual/abi.xml | 1208 +++++++++++++++++++++++++++++++++++ 1 file changed, 1208 insertions(+) create mode 100644 libstdc++-v3/doc/xml/manual/abi.xml (limited to 'libstdc++-v3/doc/xml/manual/abi.xml') diff --git a/libstdc++-v3/doc/xml/manual/abi.xml b/libstdc++-v3/doc/xml/manual/abi.xml new file mode 100644 index 000000000..6e7d46bfa --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/abi.xml @@ -0,0 +1,1208 @@ +
+ + +ABI Policy and Guidelines + + + C++ + + + ABI + + + version + + + dynamic + + + shared + + + compatibility + + + + + + + + + +
The C++ Interface + + + + C++ applications often depend on specific language support + routines, say for throwing exceptions, or catching exceptions, and + perhaps also depend on features in the C++ Standard Library. + + + + The C++ Standard Library has many include files, types defined in + those include files, specific named functions, and other + behavior. The text of these behaviors, as written in source include + files, is called the 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 available + configure options, and their impact on the library ABI, are + documented +here. + + + Putting all of these ideas together results in the C++ Standard +library ABI, which is the compilation of a given library API by a +given 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 (i.e., g++ and libstdc++) that + implements the C++ ABI in question. + + +
+ +
Versioning + + + The C++ interface has evolved throughout the history of the GNU +C++ toolchain. With each release, various details have been changed so +as to give distinct versions to the C++ interface. + + +
Goals + + +Extending existing, stable ABIs. Versioning gives subsequent +releases of library binaries the ability to add new symbols and add +functionality, all the while retaining compatibility with the previous +releases in the series. Thus, program binaries linked with the initial +release of a library binary will still run correctly if the library +binary is replaced by carefully-managed subsequent library +binaries. This is called forward compatibility. + + +The reverse (backwards compatibility) is not true. It is not possible +to take program binaries linked with the latest version of a library +binary in a release series (with additional symbols added), substitute +in the initial release of the library binary, and remain link +compatible. + + +Allows multiple, incompatible ABIs to coexist at the same time. + +
+ +
History + + + + 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. + + This is implemented via file names and the ELF + DT_SONAME mechanism (at least on ELF + systems). 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 + gcc-3.2.1: libgcc_s.so.1 + gcc-3.2.2: libgcc_s.so.1 + gcc-3.2.3: libgcc_s.so.1 + gcc-3.3.0: libgcc_s.so.1 + gcc-3.3.1: libgcc_s.so.1 + gcc-3.3.2: libgcc_s.so.1 + gcc-3.3.3: libgcc_s.so.1 + gcc-3.4.x, gcc-4.[0-5].x: libgcc_s.so.1 + + + For m68k-linux the versions differ as follows: + + + gcc-3.4.x, gcc-4.[0-5].x: libgcc_s.so.1 + when configuring --with-sjlj-exceptions, or + libgcc_s.so.2 + + + For hppa-linux the versions differ as follows: + + + gcc-3.4.x, gcc-4.[0-1].x: either libgcc_s.so.1 + when configuring --with-sjlj-exceptions, or + libgcc_s.so.2 + gcc-4.[2-5].x: either libgcc_s.so.3 when configuring + --with-sjlj-exceptions) or libgcc_s.so.4 + + + + + + Symbol versioning on the libgcc_s.so binary. + + It is versioned with the following labels and version + definitions, where the version definition is the maximum for a + particular release. Labels are cumulative. If a particular release + is not listed, it has the same version labels as the preceding + release. + + This corresponds to the mapfile: gcc/libgcc-std.ver + + gcc-3.0.0: GCC_3.0 + gcc-3.3.0: GCC_3.3 + gcc-3.3.1: GCC_3.3.1 + gcc-3.3.2: GCC_3.3.2 + gcc-3.3.4: GCC_3.3.4 + gcc-3.4.0: GCC_3.4 + gcc-3.4.2: GCC_3.4.2 + gcc-3.4.4: GCC_3.4.4 + gcc-4.0.0: GCC_4.0.0 + gcc-4.1.0: GCC_4.1.0 + gcc-4.2.0: GCC_4.2.0 + gcc-4.3.0: GCC_4.3.0 + gcc-4.4.0: GCC_4.4.0 + + + + + + Release versioning on the libstdc++.so binary, implemented in + the same way as the libgcc_s.so binary above. Listed is the + filename: DT_SONAME can be deduced from + the filename by removing the last two period-delimited numbers. For + example, filename libstdc++.so.5.0.4 + corresponds to a DT_SONAME of + libstdc++.so.5. Binaries with equivalent + DT_SONAMEs are forward-compatibile: in + the table below, releases incompatible with the previous + one are explicitly noted. + + + 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 (See Note 1) + gcc-3.0.4: libstdc++.so.3.0.4 + gcc-3.1.0: libstdc++.so.4.0.0 (Incompatible with previous) + gcc-3.1.1: libstdc++.so.4.0.1 + gcc-3.2.0: libstdc++.so.5.0.0 (Incompatible with previous) + gcc-3.2.1: libstdc++.so.5.0.1 + gcc-3.2.2: libstdc++.so.5.0.2 + gcc-3.2.3: libstdc++.so.5.0.3 (See Note 2) + gcc-3.3.0: libstdc++.so.5.0.4 + gcc-3.3.1: libstdc++.so.5.0.5 + gcc-3.3.2: libstdc++.so.5.0.5 + gcc-3.3.3: libstdc++.so.5.0.5 + gcc-3.4.0: libstdc++.so.6.0.0 (Incompatible with previous) + gcc-3.4.1: libstdc++.so.6.0.1 + gcc-3.4.2: libstdc++.so.6.0.2 + gcc-3.4.3: libstdc++.so.6.0.3 + gcc-3.4.4: libstdc++.so.6.0.3 + gcc-3.4.5: libstdc++.so.6.0.3 + gcc-3.4.6: libstdc++.so.6.0.3 + gcc-4.0.0: libstdc++.so.6.0.4 + gcc-4.0.1: libstdc++.so.6.0.5 + gcc-4.0.2: libstdc++.so.6.0.6 + gcc-4.0.3: libstdc++.so.6.0.7 + gcc-4.1.0: libstdc++.so.6.0.7 + gcc-4.1.1: libstdc++.so.6.0.8 + gcc-4.1.2: libstdc++.so.6.0.8 + gcc-4.2.0: libstdc++.so.6.0.9 + gcc-4.2.1: libstdc++.so.6.0.9 (See Note 3) + gcc-4.2.2: libstdc++.so.6.0.9 + gcc-4.2.3: libstdc++.so.6.0.9 + gcc-4.2.4: libstdc++.so.6.0.9 + gcc-4.3.0: libstdc++.so.6.0.10 + gcc-4.3.1: libstdc++.so.6.0.10 + gcc-4.3.2: libstdc++.so.6.0.10 + gcc-4.3.3: libstdc++.so.6.0.10 + gcc-4.3.4: libstdc++.so.6.0.10 + gcc-4.4.0: libstdc++.so.6.0.11 + gcc-4.4.1: libstdc++.so.6.0.12 + gcc-4.4.2: libstdc++.so.6.0.13 + gcc-4.5.0: libstdc++.so.6.0.14 + + + Note 1: Error should be libstdc++.so.3.0.3. + + + Note 2: Not strictly required. + + + Note 3: This release (but not previous or subsequent) has one + known incompatibility, see 33678 + in the GCC bug database. + + + + Symbol versioning on the libstdc++.so binary. + + mapfile: libstdc++-v3/config/abi/pre/gnu.ver + It is versioned with the following labels and version + definitions, where the version definition is the maximum for a + particular release. Note, only symbols which are newly introduced + will use the maximum version definition. Thus, for release series + with the same label, but incremented version definitions, the later + release has both versions. (An example of this would be the + gcc-3.2.1 release, which has GLIBCPP_3.2.1 for new symbols and + GLIBCPP_3.2 for symbols that were introduced in the gcc-3.2.0 + release.) If a particular release is not listed, it has the same + version labels as the preceding release. + + + gcc-3.0.0: (Error, not versioned) + gcc-3.0.1: (Error, not versioned) + gcc-3.0.2: (Error, not versioned) + gcc-3.0.3: (Error, not versioned) + gcc-3.0.4: (Error, not versioned) + 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 + gcc-3.2.1: GLIBCPP_3.2.1, CXXABI_1.2 + gcc-3.2.2: GLIBCPP_3.2.2, CXXABI_1.2 + gcc-3.2.3: GLIBCPP_3.2.2, CXXABI_1.2 + gcc-3.3.0: GLIBCPP_3.2.2, CXXABI_1.2.1 + gcc-3.3.1: GLIBCPP_3.2.3, CXXABI_1.2.1 + gcc-3.3.2: GLIBCPP_3.2.3, CXXABI_1.2.1 + gcc-3.3.3: GLIBCPP_3.2.3, CXXABI_1.2.1 + gcc-3.4.0: GLIBCXX_3.4, CXXABI_1.3 + gcc-3.4.1: GLIBCXX_3.4.1, CXXABI_1.3 + gcc-3.4.2: GLIBCXX_3.4.2 + gcc-3.4.3: GLIBCXX_3.4.3 + gcc-4.0.0: GLIBCXX_3.4.4, CXXABI_1.3.1 + gcc-4.0.1: GLIBCXX_3.4.5 + gcc-4.0.2: GLIBCXX_3.4.6 + gcc-4.0.3: GLIBCXX_3.4.7 + gcc-4.1.1: GLIBCXX_3.4.8 + gcc-4.2.0: GLIBCXX_3.4.9 + gcc-4.3.0: GLIBCXX_3.4.10, CXXABI_1.3.2 + gcc-4.4.0: GLIBCXX_3.4.11, CXXABI_1.3.3 + gcc-4.4.1: GLIBCXX_3.4.12, CXXABI_1.3.3 + gcc-4.4.2: GLIBCXX_3.4.13, CXXABI_1.3.3 + gcc-4.5.0: GLIBCXX_3.4.14, CXXABI_1.3.4 + + + + + 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 was defined in the file "lang-specs.h" in the gcc/cp directory. + Later versions defined it in "c-common.c" in the gcc directory, and from + G++ 3.4 it is defined in c-cppbuiltin.c and its value determined by the + '-fabi-version' command line option. + + + + It is versioned as follows, where 'n' is given by '-fabi-version=n': + + + gcc-3.0.x: 100 + gcc-3.1.x: 100 (Error, should be 101) + gcc-3.2.x: 102 + gcc-3.3.x: 102 + gcc-3.4.x, gcc-4.[0-5].x: 102 (when n=1) + gcc-3.4.x, gcc-4.[0-5].x: 1000 + n (when n>1) + gcc-3.4.x, gcc-4.[0-5].x: 999999 (when n=0) + + + + + + Changes to the default compiler option for + -fabi-version. + + + It is versioned as follows: + + + gcc-3.0.x: (Error, not versioned) + gcc-3.1.x: (Error, not versioned) + gcc-3.2.x: -fabi-version=1 + gcc-3.3.x: -fabi-version=1 + gcc-3.4.x, gcc-4.[0-5].x: -fabi-version=2 (Incompatible with previous) + + + + + + Incremental bumping of a library pre-defined macro. For releases + before 3.4.0, the macro is __GLIBCPP__. For later releases, it's + __GLIBCXX__. (The libstdc++ project generously changed from CPP to + CXX throughout its source to allow the "C" pre-processor the CPP + macro namespace.) These macros are 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. (Up to gcc-4.1.0, it was + changed every night by an automated script. Since gcc-4.1.0, it is + the same value as gcc/DATESTAMP.) + + + 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 + gcc-3.2.1: 20021119 + gcc-3.2.2: 20030205 + gcc-3.2.3: 20030422 + gcc-3.3.0: 20030513 + gcc-3.3.1: 20030804 + gcc-3.3.2: 20031016 + gcc-3.3.3: 20040214 + gcc-3.4.0: 20040419 + gcc-3.4.1: 20040701 + gcc-3.4.2: 20040906 + gcc-3.4.3: 20041105 + gcc-3.4.4: 20050519 + gcc-3.4.5: 20051201 + gcc-3.4.6: 20060306 + gcc-4.0.0: 20050421 + gcc-4.0.1: 20050707 + gcc-4.0.2: 20050921 + gcc-4.0.3: 20060309 + gcc-4.1.0: 20060228 + gcc-4.1.1: 20060524 + gcc-4.1.2: 20070214 + gcc-4.2.0: 20070514 + gcc-4.2.1: 20070719 + gcc-4.2.2: 20071007 + gcc-4.2.3: 20080201 + gcc-4.2.4: 20080519 + gcc-4.3.0: 20080306 + gcc-4.3.1: 20080606 + gcc-4.3.2: 20080827 + gcc-4.3.3: 20090124 + gcc-4.4.0: 20090421 + gcc-4.4.1: 20090722 + gcc-4.4.2: 20091015 + + + + + + + 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, and is deprecated in 3.4 (where it + is called _GLIBCXX_VERSION). + + + + 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" + gcc-3.2.1: "3.2.1" + gcc-3.2.2: "3.2.2" + gcc-3.2.3: "3.2.3" + gcc-3.3.0: "3.3" + gcc-3.3.1: "3.3.1" + gcc-3.3.2: "3.3.2" + gcc-3.3.3: "3.3.3" + gcc-3.4.x: "version-unused" + gcc-4.[0-5].x: "version-unused" + + + + + + + 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 GLIBCXX_CONFIGURE (GLIBCPP_CONFIGURE before gcc-3.4.0). + + + 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 + gcc-3.2.1: include/c++/3.2.1 + gcc-3.2.2: include/c++/3.2.2 + gcc-3.2.3: include/c++/3.2.3 + gcc-3.3.0: include/c++/3.3 + gcc-3.3.1: include/c++/3.3.1 + gcc-3.3.2: include/c++/3.3.2 + gcc-3.3.3: include/c++/3.3.3 + gcc-3.4.0: include/c++/3.4.0 + gcc-3.4.1: include/c++/3.4.1 + gcc-3.4.2: include/c++/3.4.2 + gcc-3.4.3: include/c++/3.4.3 + gcc-3.4.4: include/c++/3.4.4 + gcc-3.4.5: include/c++/3.4.5 + gcc-3.4.6: include/c++/3.4.6 + gcc-4.0.0: include/c++/4.0.0 + gcc-4.0.1: include/c++/4.0.1 + gcc-4.0.2: include/c++/4.0.2 + gcc-4.0.3: include/c++/4.0.3 + gcc-4.1.0: include/c++/4.1.0 + gcc-4.1.1: include/c++/4.1.1 + gcc-4.1.2: include/c++/4.1.2 + gcc-4.2.0: include/c++/4.2.0 + gcc-4.2.1: include/c++/4.2.1 + gcc-4.2.2: include/c++/4.2.2 + gcc-4.2.3: include/c++/4.2.3 + gcc-4.2.4: include/c++/4.2.4 + gcc-4.3.0: include/c++/4.3.0 + gcc-4.3.1: include/c++/4.3.1 + gcc-4.3.3: include/c++/4.3.3 + gcc-4.3.4: include/c++/4.3.4 + gcc-4.4.0: include/c++/4.4.0 + gcc-4.4.1: include/c++/4.4.1 + gcc-4.4.2: include/c++/4.4.2 + gcc-4.5.0: include/c++/4.5.0 + + + + + + + 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. + + + +
+ +
Prerequisites + + + Minimum environment that supports a versioned ABI: A supported + dynamic linker, a GNU linker of sufficient vintage to understand + demangled C++ name globbing (ld) or the Sun linker, a shared + executable compiled + with g++, and shared libraries (libgcc_s, libstdc++) 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 and more recent vintages, will meet the + requirements above, as does Solaris 2.5 and up. + +
+ +
Configuring + + + + 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: + here + + + + There is one flag that explicitly deals with symbol versioning: + --enable-symvers. + + + + In particular, libstdc++-v3/acinclude.m4 has a macro called + GLIBCXX_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. + +
+ +
Checking Active + + + + When the GNU C++ library is being built with symbol versioning + on, you should see the following at configure time for + libstdc++: + + + + + checking versioning on shared library symbols... gnu + + + + + or another of the supported styles. + 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 and link it to the shared + libstdc++ library: + + + +#include <iostream> + +int main() +{ std::cout << "hello" << std::endl; return 0; } + +%g++ hello.cc -o hello.out + +%ldd hello.out + libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0x00764000) + libm.so.6 => /lib/tls/libm.so.6 (0x004a8000) + libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40016000) + libc.so.6 => /lib/tls/libc.so.6 (0x0036d000) + /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000) + +%nm hello.out + + + +If you see symbols in the resulting output with "GLIBCXX_3" as part +of the name, then the executable is versioned. Here's an example: + + + + U _ZNSt8ios_base4InitC1Ev@@GLIBCXX_3.4 + + + +On Solaris 2, you can use pvs -r instead: + + + +%g++ hello.cc -o hello.out + +%pvs -r hello.out + libstdc++.so.6 (GLIBCXX_3.4, GLIBCXX_3.4.12); + libgcc_s.so.1 (GCC_3.0); + libc.so.1 (SUNWprivate_1.1, SYSVABI_1.3); + + + +ldd -v works too, but is very verbose. + + +
+
+ +
Allowed Changes + + + +The following will cause the library minor version number to +increase, say from "libstdc++.so.3.0.4" to "libstdc++.so.3.0.5". + + + Adding an exported global or static data member + Adding an exported function, static or non-virtual member function + Adding an exported symbol or symbols by additional instantiations + + +Other allowed changes are possible. + + +
+ +
Prohibited Changes + + + +The following non-exhaustive list will cause the library major version +number to increase, say from "libstdc++.so.3.0.4" to +"libstdc++.so.4.0.0". + + + + Changes in the gcc/g++ compiler ABI +Changing size of an exported symbol +Changing alignment of an exported symbol +Changing the layout of an exported symbol +Changing mangling on an exported symbol +Deleting an exported symbol +Changing the inheritance properties of a type by adding or removing + base classes + + 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. + + + Adding an explicit copy constructor or destructor to a +class that would otherwise have implicit versions. This will change +the way the compiler deals with this class in by-value return +statements or parameters: instead of passing instances of this +class in registers, the compiler will be forced to use memory. See the +section on Function +Calling Conventions and APIs + of the C++ ABI documentation for further details. + + + + +
+ + + +
Implementation + + + + + + Separation of interface and implementation + + + This is accomplished by two techniques that separate the API from + the ABI: forcing undefined references to link against a library + binary for definitions. + + + + + Include files have declarations, source files have defines + + + + For non-templatized types, such as much of class + locale, the appropriate standard C++ include, say + locale, can contain full declarations, while + various source files (say locale.cc, locale_init.cc, + localename.cc) contain definitions. + + + + + + Extern template on required types + + + + For parts of the standard that have an explicit list of + required instantiations, the GNU extension syntax extern + template can be used to control where template + definitions reside. By marking required instantiations as + extern template in include files, and providing + explicit instantiations in the appropriate instantiation files, + non-inlined template functions can be versioned. This technique + is mostly used on parts of the standard that require + char and wchar_t instantiations, and + includes basic_string, the locale facets, and the + types in iostreams. + + + + + + + + In addition, these techniques have the additional benefit that they + reduce binary size, which can increase runtime performance. + + + + + + Namespaces linking symbol definitions to export mapfiles + + + All symbols in the shared library binary are processed by a + linker script at build time that either allows or disallows + external linkage. Because of this, some symbols, regardless of + normal C/C++ linkage, are not visible. Symbols that are internal + have several appealing characteristics: by not exporting the + symbols, there are no relocations when the shared library is + started and thus this makes for faster runtime loading + performance by the underlying dynamic loading mechanism. In + addition, they have the possibility of changing without impacting + ABI compatibility. + + +The following namespaces are transformed by the mapfile: + + + + +namespace std + Defaults to exporting all symbols in label +GLIBCXX that do not begin with an underscore, i.e., +__test_func would not be exported by default. Select +exceptional symbols are allowed to be visible. + + + +namespace __gnu_cxx + Defaults to not exporting any symbols in label +GLIBCXX, select items are allowed to be visible. + + + +namespace __gnu_internal + Defaults to not exported, no items are allowed to be visible. + + + +namespace __cxxabiv1, aliased to namespace abi + Defaults to not exporting any symbols in label +CXXABI, select items are allowed to be visible. + + + + + + + + Freezing the API + Disallowed changes, as above, are not made on a stable release +branch. Enforcement tends to be less strict with GNU extensions that +standard includes. + + + +
+ +
Testing + + +
Single ABI Testing + + + + 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. + + + +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++ Makefile. + + + +This is a proactive check of 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.4.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. + +Notice that each baseline is relative to a default +configured library and compiler: in particular, if options such as +--enable-clocale, or --with-cpu, in case of multilibs, are used at +configure time, the check may fail, either because of substantive +differences or because of limitations of the current checking +machinery. + + + +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 PR 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! + + +
+
Multiple ABI Testing + + +A "C" application, dynamically linked to two shared libraries, liba, +libb. The dependent library liba is a C++ shared library compiled with +gcc-3.3.x, and uses io, exceptions, locale, etc. The dependent library +libb is a C++ shared library compiled with gcc-3.4.x, and also uses io, +exceptions, locale, etc. + + + As above, libone is constructed as follows: + +%$bld/H-x86-gcc-3.4.0/bin/g++ -fPIC -DPIC -c a.cc + +%$bld/H-x86-gcc-3.4.0/bin/g++ -shared -Wl,-soname -Wl,libone.so.1 -Wl,-O1 -Wl,-z,defs a.o -o libone.so.1.0.0 + +%ln -s libone.so.1.0.0 libone.so + +%$bld/H-x86-gcc-3.4.0/bin/g++ -c a.cc + +%ar cru libone.a a.o + + + And, libtwo is constructed as follows: + + +%$bld/H-x86-gcc-3.3.3/bin/g++ -fPIC -DPIC -c b.cc + +%$bld/H-x86-gcc-3.3.3/bin/g++ -shared -Wl,-soname -Wl,libtwo.so.1 -Wl,-O1 -Wl,-z,defs b.o -o libtwo.so.1.0.0 + +%ln -s libtwo.so.1.0.0 libtwo.so + +%$bld/H-x86-gcc-3.3.3/bin/g++ -c b.cc + +%ar cru libtwo.a b.o + + + ...with the resulting libraries looking like + + + +%ldd libone.so.1.0.0 + libstdc++.so.6 => /usr/lib/libstdc++.so.6 (0x40016000) + libm.so.6 => /lib/tls/libm.so.6 (0x400fa000) + libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x4011c000) + libc.so.6 => /lib/tls/libc.so.6 (0x40125000) + /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000) + +%ldd libtwo.so.1.0.0 + libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0x40027000) + libm.so.6 => /lib/tls/libm.so.6 (0x400e1000) + libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40103000) + libc.so.6 => /lib/tls/libc.so.6 (0x4010c000) + /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000) + + + + + Then, the "C" compiler is used to compile a source file that uses + functions from each library. + + +gcc test.c -g -O2 -L. -lone -ltwo /usr/lib/libstdc++.so.5 /usr/lib/libstdc++.so.6 + + + + Which gives the expected: + + + + +%ldd a.out + libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0x00764000) + libstdc++.so.6 => /usr/lib/libstdc++.so.6 (0x40015000) + libc.so.6 => /lib/tls/libc.so.6 (0x0036d000) + libm.so.6 => /lib/tls/libm.so.6 (0x004a8000) + libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x400e5000) + /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000) + + + + + This resulting binary, when executed, will be able to safely use + code from both liba, and the dependent libstdc++.so.6, and libb, + with the dependent libstdc++.so.5. + +
+
+ +
Outstanding Issues + + + + Some features in the C++ language make versioning especially + difficult. In particular, compiler generated constructs such as + implicit instantiations for templates, typeinfo information, and + virtual tables all may cause ABI leakage across shared library + boundaries. Because of this, mixing C++ ABIs is not recommended at + this time. + + + + For more background on this issue, see these bugzilla entries: + + + +24660: versioning weak symbols in libstdc++ + + + +19664: libstdc++ headers should have pop/push of the visibility around the declarations + + +
+ +Bibliography + + + + + + + ABIcheck, a vague idea of checking ABI compatibility + + + + + + + + C++ ABI Reference + + + + + + + + Intel Compilers for Linux Compatibility with the GNU Compilers + + + + + + + + Linker and Libraries Guide (document 819-0690) + + + + + + + + + Sun Studio 11: C++ Migration Guide (document 819-3689) + + + + + + + + How to Write Shared Libraries + + + + + UlrichDrepper + + + + + + + + + C++ ABI for the ARM Architecture + + + + + + + + Dynamic Shared Objects: Survey and Issues + + + ISO C++ J16/06-0046 + + BenjaminKosnik + + + + + + + Versioning With Namespaces + + + ISO C++ J16/06-0083 + + BenjaminKosnik + + + + + + + Binary Compatibility of Shared Libraries Implemented in C++ + on GNU/Linux Systems + + + + SYRCoSE 2009 + + PavelShved + DenisSilakov + + + +
-- cgit v1.2.3