libstdc++-v3/docs/html/abi.txt

   1
   2 ===========================
   3
   4 See http://gcc.gnu.org/ml/libstdc++/2002-07/msg00054.html for why this
   5 document exists, why it's incomplete, and what needs to be done still.
   6
   7 ===========================
   8
   9 2002-07-01 Benjamin Kosnik
  10
  11 Description of the libstdc++ ABI.
  12
  13 I. What is an ABI? What's covered? What's not?
  14
  15 - What's the deal with C++? Why can't different compiler's object
  16   files link with each other? Bug? Feature?
  17
  18 - scope of document, of use to system integrators.
  19
  20 - compilation includes and linked library binary must match up..
  21
  22 - library ABI, compiler ABI different (but effects)
  23
  24 - GNU C++ does not have a compiler command line option to switch
  25   between various different C++ ABIs. For instance, there is no way to
  26   switch between the gcc-3.0.x ABI, gcc-3.1.x ABI, and the gcc-3.2.x
  27   ABI during compilation. Other C++ compilers do allow this, and some
  28   g++ command line options may change the ABI (-fno-exceptions, see
  29   the complete list), but there is no version switch. Sorry. The GNU
  30   Project recommends that
  31
  32 - shared library only, static is immutable.
  33
  34 - Minimum environment that supports a versioned ABI: what's needed?  A
  35   supported dynamic linker, a GNU linker of sufficient vintage to
  36   understand demangled C++ name globbing (ld), a shared executable
  37   compiled with g++, and shared libraries (libgcc_s, libstdc++-v3)
  38   compiled by a compiler (g++) with a compatible ABI. Phew.
  39
  40   On top of all that, an additional constraint: libstdc++ did not
  41   attempt to version symbols (or age gracefully, really) until version
  42   3.1.0.
  43
  44   Most modern Linux and BSD versions, particularly ones using
  45   gcc-3.1.x tools, will meet the requirements above.
  46
  47 - What configure options impact symbol versioning?
  48   There is only one: --enable-symvers. For more information see:
  49   http://gcc.gnu.org/onlinedocs/libstdc++/configopts.html
  50
  51   In particular, libstdc++-v3/acinclude.m4 has a macro called
  52   GLIBCPP_ENABLE_SYMVERS that defaults to yes (or the argument passed
  53   in via --enable-symvers=foo). At that point, the macro attempts to
  54   make sure that all the requirement for symbol versioning are in
  55   place. For more information, please consult acinclude.m4.
  56
  57 - How can I tell if symbol versioning is, indeed, active?
  58
  59   When the GNU C++ library is being built with symbol versioning on,
  60   you should see the following at configure time for libstdc++-v3:
  61
  62 checking versioning on shared library symbols... gnu
  63
  64   If you don't see this line in the configure output, or if this line
  65   appears but the last word is 'no', then you are out of luck.
  66
  67   If the compiler is pre-installed, a quick way to test is to compile
  68   the following (or any) simple C++ file:
  69
  70 #include <iostream>
  71
  72 int main()
  73 { std::cout << "hello" << std::endl; return 0; }
  74
  75 %g++ hello.cc -o hello.out
  76 %nm hello.out
  77
  78 If you see symbols in the resulting output with "GLIBCPP_3.x" as part
  79 of the name, then the executable is versioned. Here's an example:
  80
  81          U _ZNSt8ios_base4InitC1Ev@@GLIBCPP_3.1
  82
  83
  84
  85
  86
  87
  88 II. ABI changes
  89
  90 - (anything) changing size of an exported symbol
  91
  92 - (anything) changing alignment of an exported symbol
  93
  94 - (anything) changing the layout of an exported symbol
  95
  96 - (anything) changing mangling on an exported symbol
  97
  98 - (anything) adding or deleting an exported symbol
  99
 100
 101 III. Versioning
 102
 103 - include files
 104
 105   - versioning headers with version, why necessary
 106     (need to control member/non-member functions, add delete files)
 107
 108 - shared library binaries
 109
 110   - release versions
 111
 112   - libtool versions
 113
 114   - when does so version get a bump? what are the options?
 115
 116   - how is the link map used?
 117
 118   - in an non-abi breaking minor release, how are symbols added?
 119     removed?
 120
 121   - in an abi-breaking major release, what happens? symbol fall back
 122
 123
 124 IV. Testing ABI changes
 125
 126 - 'make check-abi'??
 127
 128 - other ABI checkers
 129
 130
 131 V. Issues not directly addressed, and possible suggestions
 132
 133 - what to do about multi-ABI systems (nathan scenario)?
 134
 135   - compatibility libs
 136
 137   --enable-version-specific-runtime-libs
 138
 139   - Alexandre Oliva proposal to have extended name attributes, modify ld
 140
 141   - directory-level versioning
 142
 143 - wrapping C++ API's n "C" to use the C ABI.
 144
 145
 146 V. References
 147
 148 ABIcheck, a vauge idea of checking ABI compatibility
 149 http://abicheck.sourceforge.net/
 150
 151 C++ ABI reference
 152 http://www.codesourcery.com/cxx-abi/
 153
 154 Intel ABI documentation
 155 "Intel® Compilers for Linux* -Compatibility with the GNU Compilers"
 156 (included in icc 6.0)
 157
 158 Sun Solaris 2.9 docs
 159 Linker and Libraries Guide (document 816-1386)
 160 C++ Migration Guide (document 816-2459)
 161 http://docs.sun.com/db/prod/solaris.9
 162 http://docs.sun.com/?p=/doc/816-1386&a=load
 163
 164 Ulrich Drepper, "ELF Symbol Versioning"
 165 http://people.redhat.com/drepper/symbol-versioning
 166