libstdc++-v3/doc/html/manual/abi.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ABI Policy and Guidelines</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="&#10;      C++&#10;    , &#10;      ABI&#10;    , &#10;      version&#10;    , &#10;      dynamic&#10;    , &#10;      shared&#10;    " /><meta name="keywords" content="&#10;      ISO C++&#10;    , &#10;      library&#10;    " /><link rel="start" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="appendix_porting.html" title="Appendix B. Porting and Maintenance" /><link rel="prev" href="internals.html" title="Porting to New Hardware or Operating Systems" /><link rel="next" href="api.html" title="API Evolution and Deprecation History" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">ABI Policy and Guidelines</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="internals.html">Prev</a> </td><th width="60%" align="center">Appendix B. Porting and Maintenance</th><td width="20%" align="right"> <a accesskey="n" href="api.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="appendix.porting.abi"></a>ABI Policy and Guidelines</h2></div></div></div><p>
   4 </p><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="abi.cxx_interface"></a>The C++ Interface</h3></div></div></div><p>
   5   C++ applications often dependent on specific language support
   6   routines, say for throwing exceptions, or catching exceptions, and
   7   perhaps also dependent on features in the C++ Standard Library.
   8 </p><p>
   9   The C++ Standard Library has many include files, types defined in
  10   those include files, specific named functions, and other
  11   behavior. The text of these behaviors, as written in source include
  12   files, is called the Application Programing Interface, or API.
  13 </p><p>
  14   Furthermore, C++ source that is compiled into object files is
  15   transformed by the compiler: it arranges objects with specific
  16   alignment and in a particular layout, mangling names according to a
  17   well-defined algorithm, has specific arrangements for the support of
  18   virtual functions, etc. These details are defined as the compiler
  19   Application Binary Interface, or ABI. The GNU C++ compiler uses an
  20   industry-standard C++ ABI starting with version 3. Details can be
  21   found in the <a class="ulink" href="http://www.codesourcery.com/cxx-abi/abi.html" target="_top"> ABI
  22   specification</a>.
  23 </p><p>
  24  The GNU C++ compiler, g++, has a compiler command line option to
  25   switch between various different C++ ABIs. This explicit version
  26   switch is the flag <code class="code">-fabi-version</code>. In addition, some
  27   g++ command line options may change the ABI as a side-effect of
  28   use. Such flags include <code class="code">-fpack-struct</code> and
  29   <code class="code">-fno-exceptions</code>, but include others: see the complete
  30   list in the GCC manual under the heading <a class="ulink" href="http://gcc.gnu.org/onlinedocs/gcc/Code-Gen-Options.html#Code%20Gen%20Options" target="_top">Options
  31   for Code Generation Conventions</a>.
  32 </p><p>
  33   The configure options used when building a specific libstdc++
  34   version may also impact the resulting library ABI. The available
  35   configure options, and their impact on the library ABI, are
  36   documented
  37 <a class="ulink" href="http://gcc.gnu.org/onlinedocs/libstdc++/configopts.html" target="_top">
  38 here</a>.
  39 </p><p> Putting all of these ideas together results in the C++ Standard
  40 library ABI, which is the compilation of a given library API by a
  41 given compiler ABI. In a nutshell:
  42 </p><p>
  43   “<span class="quote">
  44     library API + compiler ABI = library ABI
  45   </span>”
  46 </p><p>
  47  The library ABI is mostly of interest for end-users who have
  48  unresolved symbols and are linking dynamically to the C++ Standard
  49  library, and who thus must be careful to compile their application
  50  with a compiler that is compatible with the available C++ Standard
  51  library binary. In this case, compatible is defined with the equation
  52  above: given an application compiled with a given compiler ABI and
  53  library API, it will work correctly with a Standard C++ Library
  54  created with the same constraints.
  55 </p><p>
  56   To use a specific version of the C++ ABI, one must use a
  57   corresponding GNU C++ toolchain (i.e., g++ and libstdc++) that
  58   implements the C++ ABI in question.
  59 </p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="abi.versioning"></a>Versioning</h3></div></div></div><p> The C++ interface has evolved throughout the history of the GNU
  60 C++ toolchain. With each release, various details have been changed so
  61 as to give distinct versions to the C++ interface.
  62 </p><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="abi.versioning.goals"></a>Goals</h4></div></div></div><p>Extending existing, stable ABIs. Versioning gives subsequent stable
  63 releases series libraries the ability to add new symbols and add
  64 functionality, all the while retaining backwards compatibility with
  65 the previous releases in the series. Note: the reverse is not true. It
  66 is not possible to take binaries linked with the latest version of a
  67 release series (if symbols have been added) and expect the initial
  68 release of the series to remain link compatible.
  69 </p><p>Allows multiple, incompatible ABIs to coexist at the same time.
  70 </p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="abi.versioning.history"></a>History</h4></div></div></div><p>
  71  How can this complexity be managed? What does C++ versioning mean?
  72   Because library and compiler changes often make binaries compiled
  73   with one version of the GNU tools incompatible with binaries
  74   compiled with other (either newer or older) versions of the same GNU
  75   tools, specific techniques are used to make managing this complexity
  76   easier.
  77 </p><p>
  78   The following techniques are used:
  79 </p><div class="orderedlist"><ol type="1"><li><p>Release versioning on the libgcc_s.so binary. </p><p>This is implemented via file names and the ELF DT_SONAME
  80     mechanism (at least on ELF systems). It is versioned as follows:
  81     </p><div class="itemizedlist"><ul type="disc"><li><p>gcc-3.0.0: libgcc_s.so.1</p></li><li><p>gcc-3.0.1: libgcc_s.so.1</p></li><li><p>gcc-3.0.2: libgcc_s.so.1</p></li><li><p>gcc-3.0.3: libgcc_s.so.1</p></li><li><p>gcc-3.0.4: libgcc_s.so.1</p></li><li><p>gcc-3.1.0: libgcc_s.so.1</p></li><li><p>gcc-3.1.1: libgcc_s.so.1</p></li><li><p>gcc-3.2.0: libgcc_s.so.1</p></li><li><p>gcc-3.2.1: libgcc_s.so.1</p></li><li><p>gcc-3.2.2: libgcc_s.so.1</p></li><li><p>gcc-3.2.3: libgcc_s.so.1</p></li><li><p>gcc-3.3.0: libgcc_s.so.1</p></li><li><p>gcc-3.3.1: libgcc_s.so.1</p></li><li><p>gcc-3.3.2: libgcc_s.so.1</p></li><li><p>gcc-3.3.3: libgcc_s.so.1</p></li><li><p>gcc-3.4.x, gcc-4.0.x, gcc-4.1.x, gcc-4.2.x: on m68k-linux and
  82     hppa-linux this is either libgcc_s.so.1 (when configuring
  83     <code class="code">--with-sjlj-exceptions</code>) or libgcc_s.so.2. For all
  84     others, this is libgcc_s.so.1.  </p></li></ul></div></li><li><p>Symbol versioning on the libgcc_s.so binary.</p><p>It is versioned with the following labels and version
  85    definitions, where the version definition is the maximum for a
  86    particular release. Labels are cumulative. If a particular release
  87    is not listed, it has the same version labels as the preceding
  88    release.</p><p>This corresponds to the mapfile: gcc/libgcc-std.ver</p><div class="itemizedlist"><ul type="disc"><li><p>gcc-3.0.0: GCC_3.0</p></li><li><p>gcc-3.3.0: GCC_3.3</p></li><li><p>gcc-3.3.1: GCC_3.3.1</p></li><li><p>gcc-3.3.2: GCC_3.3.2</p></li><li><p>gcc-3.3.4: GCC_3.3.4</p></li><li><p>gcc-3.4.0: GCC_3.4</p></li><li><p>gcc-3.4.2: GCC_3.4.2</p></li><li><p>gcc-3.4.4: GCC_3.4.4</p></li><li><p>gcc-4.0.0: GCC_4.0.0</p></li><li><p>gcc-4.1.0: GCC_4.1.0</p></li><li><p>gcc-4.2.0: GCC_4.2.0</p></li></ul></div></li><li><p>Release versioning on the libstdc++.so binary, implemented in the same was as the libgcc_s.so binary, above.</p><p>It is versioned as follows:
  89     </p><div class="itemizedlist"><ul type="disc"><li><p>gcc-3.0.0: libstdc++.so.3.0.0</p></li><li><p>gcc-3.0.1: libstdc++.so.3.0.1</p></li><li><p>gcc-3.0.2: libstdc++.so.3.0.2</p></li><li><p>gcc-3.0.3: libstdc++.so.3.0.2 (Error should be libstdc++.so.3.0.3)</p></li><li><p>gcc-3.0.4: libstdc++.so.3.0.4</p></li><li><p>gcc-3.1.0: libstdc++.so.4.0.0</p></li><li><p>gcc-3.1.1: libstdc++.so.4.0.1</p></li><li><p>gcc-3.2.0: libstdc++.so.5.0.0</p></li><li><p>gcc-3.2.1: libstdc++.so.5.0.1</p></li><li><p>gcc-3.2.2: libstdc++.so.5.0.2</p></li><li><p>gcc-3.2.3: libstdc++.so.5.0.3 (Not strictly required)</p></li><li><p>gcc-3.3.0: libstdc++.so.5.0.4</p></li><li><p>gcc-3.3.1: libstdc++.so.5.0.5</p></li><li><p>gcc-3.3.2: libstdc++.so.5.0.5</p></li><li><p>gcc-3.3.3: libstdc++.so.5.0.5</p></li><li><p>gcc-3.4.0: libstdc++.so.6.0.0</p></li><li><p>gcc-3.4.1: libstdc++.so.6.0.1</p></li><li><p>gcc-3.4.2: libstdc++.so.6.0.2</p></li><li><p>gcc-3.4.3: libstdc++.so.6.0.3</p></li><li><p>gcc-3.4.4: libstdc++.so.6.0.3</p></li><li><p>gcc-3.4.5: libstdc++.so.6.0.3</p></li><li><p>gcc-3.4.6: libstdc++.so.6.0.3</p></li><li><p>gcc-4.0.0: libstdc++.so.6.0.4</p></li><li><p>gcc-4.0.1: libstdc++.so.6.0.5</p></li><li><p>gcc-4.0.2: libstdc++.so.6.0.6</p></li><li><p>gcc-4.0.3: libstdc++.so.6.0.7</p></li><li><p>gcc-4.1.0: libstdc++.so.6.0.7</p></li><li><p>gcc-4.1.1: libstdc++.so.6.0.8</p></li><li><p>gcc-4.1.2: libstdc++.so.6.0.8</p></li><li><p>gcc-4.2.0: libstdc++.so.6.0.9</p></li></ul></div></li><li><p>Symbol versioning on the libstdc++.so binary.</p><p>mapfile: libstdc++/config/linker-map.gnu</p><p>It is versioned with the following labels and version
  90    definitions, where the version definition is the maximum for a
  91    particular release. Note, only symbol which are newly introduced
  92    will use the maximum version definition. Thus, for release series
  93    with the same label, but incremented version definitions, the later
  94    release has both versions. (An example of this would be the
  95    gcc-3.2.1 release, which has GLIBCPP_3.2.1 for new symbols and
  96    GLIBCPP_3.2 for symbols that were introduced in the gcc-3.2.0
  97    release.) If a particular release is not listed, it has the same
  98    version labels as the preceding release.
  99    </p><div class="itemizedlist"><ul type="disc"><li><p>gcc-3.0.0: (Error, not versioned)</p></li><li><p>gcc-3.0.1: (Error, not versioned)</p></li><li><p>gcc-3.0.2: (Error, not versioned)</p></li><li><p>gcc-3.0.3: (Error, not versioned)</p></li><li><p>gcc-3.0.4: (Error, not versioned)</p></li><li><p>gcc-3.1.0: GLIBCPP_3.1, CXXABI_1</p></li><li><p>gcc-3.1.1: GLIBCPP_3.1, CXXABI_1</p></li><li><p>gcc-3.2.0: GLIBCPP_3.2, CXXABI_1.2</p></li><li><p>gcc-3.2.1: GLIBCPP_3.2.1, CXXABI_1.2</p></li><li><p>gcc-3.2.2: GLIBCPP_3.2.2, CXXABI_1.2</p></li><li><p>gcc-3.2.3: GLIBCPP_3.2.2, CXXABI_1.2</p></li><li><p>gcc-3.3.0: GLIBCPP_3.2.2, CXXABI_1.2.1</p></li><li><p>gcc-3.3.1: GLIBCPP_3.2.3, CXXABI_1.2.1</p></li><li><p>gcc-3.3.2: GLIBCPP_3.2.3, CXXABI_1.2.1</p></li><li><p>gcc-3.3.3: GLIBCPP_3.2.3, CXXABI_1.2.1</p></li><li><p>gcc-3.4.0: GLIBCXX_3.4, CXXABI_1.3</p></li><li><p>gcc-3.4.1: GLIBCXX_3.4.1, CXXABI_1.3</p></li><li><p>gcc-3.4.2: GLIBCXX_3.4.2</p></li><li><p>gcc-3.4.3: GLIBCXX_3.4.3</p></li><li><p>gcc-4.0.0: GLIBCXX_3.4.4, CXXABI_1.3.1</p></li><li><p>gcc-4.0.1: GLIBCXX_3.4.5</p></li><li><p>gcc-4.0.2: GLIBCXX_3.4.6</p></li><li><p>gcc-4.0.3: GLIBCXX_3.4.7</p></li><li><p>gcc-4.1.1: GLIBCXX_3.4.8</p></li><li><p>gcc-4.2.0: GLIBCXX_3.4.9</p></li></ul></div></li><li><p>Incremental bumping of a compiler pre-defined macro,
 100     __GXX_ABI_VERSION. This macro is defined as the version of the
 101     compiler v3 ABI, with g++ 3.0.x being version 100. This macro will
 102     be automatically defined whenever g++ is used (the curious can
 103     test this by invoking g++ with the '-v' flag.)
 104     </p><p>
 105     This macro was defined in the file "lang-specs.h" in the gcc/cp directory.
 106     Later versions defined it in "c-common.c" in the gcc directory, and from
 107     G++ 3.4 it is defined in c-cppbuiltin.c and its value determined by the
 108     '-fabi-version' command line option.
 109     </p><p>
 110     It is versioned as follows, where 'n' is given by '-fabi-version=n':
 111     </p><div class="itemizedlist"><ul type="disc"><li><p>gcc-3.0.x: 100</p></li><li><p>gcc-3.1.x: 100 (Error, should be 101)</p></li><li><p>gcc-3.2.x: 102</p></li><li><p>gcc-3.3.x: 102</p></li><li><p>gcc-3.4.x, gcc-4.0.x, gcc-4.1.x, gcc-4.2.x: 102 (when n=1)</p></li><li><p>gcc-3.4.x, gcc-4.0.x, gcc-4.1.x, gcc-4.2.x: 1000 + n (when n&gt;1)</p></li><li><p>gcc-3.4.x, gcc-4.0.x, gcc-4.1.x, gcc-4.2.x: 999999 (when n=0)</p></li></ul></div><p></p></li><li><p>Changes to the default compiler option for
 112     <code class="code">-fabi-version</code>.
 113     </p><p>
 114     It is versioned as follows:
 115     </p><div class="itemizedlist"><ul type="disc"><li><p>gcc-3.0.x: (Error, not versioned) </p></li><li><p>gcc-3.1.x: (Error, not versioned) </p></li><li><p>gcc-3.2.x: <code class="code">-fabi-version=1</code></p></li><li><p>gcc-3.3.x: <code class="code">-fabi-version=1</code></p></li><li><p>gcc-3.4.x, gcc-4.0.x, gcc-4.1.x, gcc-4.2.x: <code class="code">-fabi-version=2</code></p></li></ul></div><p></p></li><li><p>Incremental bumping of a library pre-defined macro. For releases
 116     before 3.4.0, the macro is __GLIBCPP__. For later releases, it's
 117     __GLIBCXX__. (The libstdc++ project generously changed from CPP to
 118     CXX throughout its source to allow the "C" pre-processor the CPP
 119     macro namespace.) These macros are defined as the date the library
 120     was released, in compressed ISO date format, as an unsigned long.
 121     </p><p>
 122     This macro is defined in the file "c++config" in the
 123     "libstdc++/include/bits" directory. (Up to gcc-4.1.0, it was
 124     changed every night by an automated script. Since gcc-4.1.0, it is
 125     the same value as gcc/DATESTAMP.)
 126     </p><p>
 127     It is versioned as follows:
 128     </p><div class="itemizedlist"><ul type="disc"><li><p>gcc-3.0.0: 20010615</p></li><li><p>gcc-3.0.1: 20010819</p></li><li><p>gcc-3.0.2: 20011023</p></li><li><p>gcc-3.0.3: 20011220</p></li><li><p>gcc-3.0.4: 20020220</p></li><li><p>gcc-3.1.0: 20020514</p></li><li><p>gcc-3.1.1: 20020725</p></li><li><p>gcc-3.2.0: 20020814</p></li><li><p>gcc-3.2.1: 20021119</p></li><li><p>gcc-3.2.2: 20030205</p></li><li><p>gcc-3.2.3: 20030422</p></li><li><p>gcc-3.3.0: 20030513</p></li><li><p>gcc-3.3.1: 20030804</p></li><li><p>gcc-3.3.2: 20031016</p></li><li><p>gcc-3.3.3: 20040214</p></li><li><p>gcc-3.4.0: 20040419</p></li><li><p>gcc-3.4.1: 20040701</p></li><li><p>gcc-3.4.2: 20040906</p></li><li><p>gcc-3.4.3: 20041105</p></li><li><p>gcc-3.4.4: 20050519</p></li><li><p>gcc-3.4.5: 20051201</p></li><li><p>gcc-3.4.6: 20060306</p></li><li><p>gcc-4.0.0: 20050421</p></li><li><p>gcc-4.0.1: 20050707</p></li><li><p>gcc-4.0.2: 20050921</p></li><li><p>gcc-4.0.3: 20060309</p></li><li><p>gcc-4.1.0: 20060228</p></li><li><p>gcc-4.1.1: 20060524</p></li><li><p>gcc-4.1.2: 20070214</p></li><li><p>gcc-4.2.0: 20070514</p></li></ul></div><p></p></li><li><p>
 129     Incremental bumping of a library pre-defined macro,
 130     _GLIBCPP_VERSION. This macro is defined as the released version of
 131     the library, as a string literal. This is only implemented in
 132     gcc-3.1.0 releases and higher, and is deprecated in 3.4 (where it
 133     is called _GLIBCXX_VERSION).
 134     </p><p>
 135     This macro is defined in the file "c++config" in the
 136     "libstdc++/include/bits" directory and is generated
 137     automatically by autoconf as part of the configure-time generation
 138     of config.h.
 139     </p><p>
 140     It is versioned as follows:
 141     </p><div class="itemizedlist"><ul type="disc"><li><p>gcc-3.0.0: "3.0.0"</p></li><li><p>gcc-3.0.1: "3.0.0" (Error, should be "3.0.1")</p></li><li><p>gcc-3.0.2: "3.0.0" (Error, should be "3.0.2")</p></li><li><p>gcc-3.0.3: "3.0.0" (Error, should be "3.0.3")</p></li><li><p>gcc-3.0.4: "3.0.0" (Error, should be "3.0.4")</p></li><li><p>gcc-3.1.0: "3.1.0"</p></li><li><p>gcc-3.1.1: "3.1.1"</p></li><li><p>gcc-3.2.0: "3.2"</p></li><li><p>gcc-3.2.1: "3.2.1"</p></li><li><p>gcc-3.2.2: "3.2.2"</p></li><li><p>gcc-3.2.3: "3.2.3"</p></li><li><p>gcc-3.3.0: "3.3"</p></li><li><p>gcc-3.3.1: "3.3.1"</p></li><li><p>gcc-3.3.2: "3.3.2"</p></li><li><p>gcc-3.3.3: "3.3.3"</p></li><li><p>gcc-3.4.x: "version-unused"</p></li><li><p>gcc-4.0.x: "version-unused"</p></li><li><p>gcc-4.1.x: "version-unused"</p></li><li><p>gcc-4.2.x: "version-unused"</p></li></ul></div><p></p></li><li><p>
 142     Matching each specific C++ compiler release to a specific set of
 143     C++ include files. This is only implemented in gcc-3.1.1 releases
 144     and higher.
 145     </p><p>
 146     All C++ includes are installed in include/c++, then nest in a
 147     directory hierarchy corresponding to the C++ compiler's released
 148     version. This version corresponds to the variable "gcc_version" in
 149     "libstdc++/acinclude.m4," and more details can be found in that
 150     file's macro GLIBCXX_CONFIGURE (GLIBCPP_CONFIGURE before gcc-3.4.0).
 151     </p><p>
 152     C++ includes are versioned as follows:
 153     </p><div class="itemizedlist"><ul type="disc"><li><p>gcc-3.0.0: include/g++-v3</p></li><li><p>gcc-3.0.1: include/g++-v3</p></li><li><p>gcc-3.0.2: include/g++-v3</p></li><li><p>gcc-3.0.3: include/g++-v3</p></li><li><p>gcc-3.0.4: include/g++-v3</p></li><li><p>gcc-3.1.0: include/g++-v3</p></li><li><p>gcc-3.1.1: include/c++/3.1.1</p></li><li><p>gcc-3.2.0: include/c++/3.2</p></li><li><p>gcc-3.2.1: include/c++/3.2.1</p></li><li><p>gcc-3.2.2: include/c++/3.2.2</p></li><li><p>gcc-3.2.3: include/c++/3.2.3</p></li><li><p>gcc-3.3.0: include/c++/3.3</p></li><li><p>gcc-3.3.1: include/c++/3.3.1</p></li><li><p>gcc-3.3.2: include/c++/3.3.2</p></li><li><p>gcc-3.3.3: include/c++/3.3.3</p></li><li><p>gcc-3.4.0: include/c++/3.4.0</p></li><li><p>gcc-3.4.1: include/c++/3.4.1</p></li><li><p>gcc-3.4.2: include/c++/3.4.2</p></li><li><p>gcc-3.4.3: include/c++/3.4.3</p></li><li><p>gcc-3.4.4: include/c++/3.4.4</p></li><li><p>gcc-3.4.5: include/c++/3.4.5</p></li><li><p>gcc-3.4.6: include/c++/3.4.6</p></li><li><p>gcc-4.0.0: include/c++/4.0.0</p></li><li><p>gcc-4.0.1: include/c++/4.0.1</p></li><li><p>gcc-4.0.2: include/c++/4.0.2</p></li><li><p>gcc-4.0.3: include/c++/4.0.3</p></li><li><p>gcc-4.1.0: include/c++/4.1.0</p></li><li><p>gcc-4.1.1: include/c++/4.1.1</p></li><li><p>gcc-4.1.2: include/c++/4.1.2</p></li><li><p>gcc-4.2.0: include/c++/4.2.0</p></li></ul></div><p></p></li></ol></div><p>
 154   Taken together, these techniques can accurately specify interface
 155   and implementation changes in the GNU C++ tools themselves. Used
 156   properly, they allow both the GNU C++ tools implementation, and
 157   programs using them, an evolving yet controlled development that
 158   maintains backward compatibility.
 159 </p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="abi.versioning.prereq"></a>Prerequisites</h4></div></div></div><p>
 160       Minimum environment that supports a versioned ABI: A supported
 161       dynamic linker, a GNU linker of sufficient vintage to understand
 162       demangled C++ name globbing (ld), a shared executable compiled
 163       with g++, and shared libraries (libgcc_s, libstdc++) compiled by
 164       a compiler (g++) with a compatible ABI. Phew.
 165     </p><p>
 166       On top of all that, an additional constraint: libstdc++ did not
 167       attempt to version symbols (or age gracefully, really) until
 168       version 3.1.0.
 169     </p><p>
 170       Most modern Linux and BSD versions, particularly ones using
 171       gcc-3.1.x tools and more recent vintages, will meet the
 172       requirements above.
 173     </p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="abi.versioning.config"></a>Configuring</h4></div></div></div><p>
 174       It turns out that most of the configure options that change
 175       default behavior will impact the mangled names of exported
 176       symbols, and thus impact versioning and compatibility.
 177     </p><p>
 178       For more information on configure options, including ABI
 179       impacts, see:
 180       http://gcc.gnu.org/onlinedocs/libstdc++/configopts.html
 181     </p><p>
 182       There is one flag that explicitly deals with symbol versioning:
 183       --enable-symvers.
 184     </p><p>
 185       In particular, libstdc++/acinclude.m4 has a macro called
 186       GLIBCXX_ENABLE_SYMVERS that defaults to yes (or the argument
 187       passed in via --enable-symvers=foo). At that point, the macro
 188       attempts to make sure that all the requirement for symbol
 189       versioning are in place. For more information, please consult
 190       acinclude.m4.
 191     </p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="abi.versioning.active"></a>Checking Active</h4></div></div></div><p>
 192       When the GNU C++ library is being built with symbol versioning
 193       on, you should see the following at configure time for
 194       libstdc++:
 195     </p><pre class="screen">
 196 <code class="computeroutput">
 197   checking versioning on shared library symbols... gnu
 198 </code>
 199 </pre><p>
 200   If you don't see this line in the configure output, or if this line
 201   appears but the last word is 'no', then you are out of luck.
 202 </p><p>
 203   If the compiler is pre-installed, a quick way to test is to compile
 204   the following (or any) simple C++ file and link it to the shared
 205   libstdc++ library:
 206 </p><pre class="programlisting">
 207 #include &lt;iostream&gt;
 208
 209 int main()
 210 { std::cout &lt;&lt; "hello" &lt;&lt; std::endl; return 0; }
 211
 212 %g++ hello.cc -o hello.out
 213
 214 %ldd hello.out
 215         libstdc++.so.5 =&gt; /usr/lib/libstdc++.so.5 (0x00764000)
 216         libm.so.6 =&gt; /lib/tls/libm.so.6 (0x004a8000)
 217         libgcc_s.so.1 =&gt; /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40016000)
 218         libc.so.6 =&gt; /lib/tls/libc.so.6 (0x0036d000)
 219         /lib/ld-linux.so.2 =&gt; /lib/ld-linux.so.2 (0x00355000)
 220
 221 %nm hello.out
 222 </pre><p>
 223 If you see symbols in the resulting output with "GLIBCXX_3" as part
 224 of the name, then the executable is versioned. Here's an example:
 225 </p><p>
 226    <code class="code">U _ZNSt8ios_base4InitC1Ev@@GLIBCXX_3.4</code>
 227 </p></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="abi.changes_allowed"></a>Allowed Changes</h3></div></div></div><p>
 228 The following will cause the library minor version number to
 229 increase, say from "libstdc++.so.3.0.4" to "libstdc++.so.3.0.5".
 230 </p><div class="orderedlist"><ol type="1"><li><p>Adding an exported global or static data member</p></li><li><p>Adding an exported function, static or non-virtual member function</p></li><li><p>Adding an exported symbol or symbols by additional instantiations</p></li></ol></div><p>
 231 Other allowed changes are possible.
 232 </p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="abi.changes_no"></a>Prohibited Changes</h3></div></div></div><p>
 233 The following non-exhaustive list will cause the library major version
 234 number to increase, say from "libstdc++.so.3.0.4" to
 235 "libstdc++.so.4.0.0".
 236 </p><div class="orderedlist"><ol type="1"><li><p>Changes in the gcc/g++ compiler ABI</p></li><li><p>Changing size of an exported symbol</p></li><li><p>Changing alignment of an exported symbol</p></li><li><p>Changing the layout of an exported symbol</p></li><li><p>Changing mangling on an exported symbol</p></li><li><p>Deleting an exported symbol</p></li><li><p>Changing the inheritance properties of a type by adding or removing
 237     base classes</p></li><li><p>
 238   Changing the size, alignment, or layout of types
 239   specified in the C++ standard. These may not necessarily be
 240   instantiated or otherwise exported in the library binary, and
 241   include all the required locale facets, as well as things like
 242   std::basic_streambuf, et al.
 243 </p></li><li><p> Adding an explicit copy constructor or destructor to a
 244 class that would otherwise have implicit versions. This will change
 245 the way the compiler deals with this class in by-value return
 246 statements or parameters: instead of being passing instances of this
 247 class in registers, the compiler will be forced to use memory. See <a class="ulink" href="http://www.codesourcery.com/cxx-abi/abi.html#calls" target="_top"> this part</a>
 248  of the C++ ABI documentation for further details.
 249  </p></li></ol></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="abi.impl"></a>Implementation</h3></div></div></div><div class="orderedlist"><ol type="1"><li><p>
 250      Separation of interface and implementation
 251    </p><p>
 252      This is accomplished by two techniques that separate the API from
 253      the ABI: forcing undefined references to link against a library
 254      binary for definitions.
 255    </p><div class="variablelist"><dl><dt><span class="term">Include files have declarations, source files have defines</span></dt><dd><p>
 256         For non-templatized types, such as much of <code class="code">class
 257         locale</code>, the appropriate standard C++ include, say
 258         <code class="code">locale</code>, can contain full declarations, while
 259         various source files (say <code class="code"> locale.cc, locale_init.cc,
 260         localename.cc</code>) contain definitions.
 261       </p></dd><dt><span class="term">Extern template on required types</span></dt><dd><p>
 262        For parts of the standard that have an explicit list of
 263        required instantiations, the GNU extension syntax <code class="code"> extern
 264        template </code> can be used to control where template
 265        definitions reside. By marking required instantiations as
 266        <code class="code"> extern template </code> in include files, and providing
 267        explicit instantiations in the appropriate instantiation files,
 268        non-inlined template functions can be versioned. This technique
 269        is mostly used on parts of the standard that require <code class="code">
 270        char</code> and <code class="code"> wchar_t</code> instantiations, and
 271        includes <code class="code"> basic_string</code>, the locale facets, and the
 272        types in <code class="code"> iostreams</code>.
 273      </p></dd></dl></div><p>
 274    In addition, these techniques have the additional benefit that they
 275    reduce binary size, which can increase runtime performance.
 276  </p></li><li><p>
 277      Namespaces linking symbol definitions to export mapfiles
 278    </p><p>
 279      All symbols in the shared library binary are processed by a
 280      linker script at build time that either allows or disallows
 281      external linkage. Because of this, some symbols, regardless of
 282      normal C/C++ linkage, are not visible. Symbols that are internal
 283      have several appealing characteristics: by not exporting the
 284      symbols, there are no relocations when the shared library is
 285      started and thus this makes for faster runtime loading
 286      performance by the underlying dynamic loading mechanism. In
 287      addition, they have the possibility of changing without impacting
 288      ABI compatibility.
 289    </p><p>The following namespaces are transformed by the mapfile:</p><div class="variablelist"><dl><dt><span class="term"><code class="code">namespace std</code></span></dt><dd><p> Defaults to exporting all symbols in label
 290 <code class="code">GLIBCXX</code> that do not begin with an underscore, i.e.,
 291 <code class="code">__test_func</code> would not be exported by default. Select
 292 exceptional symbols are allowed to be visible.</p></dd><dt><span class="term"><code class="code">namespace __gnu_cxx</code></span></dt><dd><p> Defaults to not exporting any symbols in label
 293 <code class="code">GLIBCXX</code>, select items are allowed to be visible.</p></dd><dt><span class="term"><code class="code">namespace __gnu_internal</code></span></dt><dd><p> Defaults to not exported, no items are allowed to be visible.</p></dd><dt><span class="term"><code class="code">namespace __cxxabiv1</code>, aliased to <code class="code"> namespace abi</code></span></dt><dd><p> Defaults to not exporting any symbols in label
 294 <code class="code">CXXABI</code>, select items are allowed to be visible.</p></dd></dl></div><p>
 295 </p></li><li><p>Freezing the API</p><p>Disallowed changes, as above, are not made on a stable release
 296 branch. Enforcement tends to be less strict with GNU extensions that
 297 standard includes.</p></li></ol></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="abi.testing"></a>Testing</h3></div></div></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="abi.testing.single"></a>Single ABI Testing</h4></div></div></div><p>
 298       Testing for GNU C++ ABI changes is composed of two distinct
 299       areas: testing the C++ compiler (g++) for compiler changes, and
 300       testing the C++ library (libstdc++) for library changes.
 301     </p><p>
 302       Testing the C++ compiler ABI can be done various ways.
 303     </p><p>
 304       One.  Intel ABI checker. More information can be obtained <a class="ulink" href="http://developer.intel.com/software/products/opensource/" target="_top">here.</a>
 305     </p><p>
 306 Two.
 307 The second is yet unreleased, but has been announced on the gcc
 308 mailing list. It is yet unspecified if these tools will be freely
 309 available, and able to be included in a GNU project. Please contact
 310 Mark Mitchell (mark@codesourcery.com) for more details, and current
 311 status.
 312 </p><p>
 313 Three.
 314 Involves using the vlad.consistency test framework. This has also been
 315 discussed on the gcc mailing lists.
 316 </p><p>
 317 Testing the C++ library ABI can also be done various ways.
 318 </p><p>
 319 One.
 320 (Brendan Kehoe, Jeff Law suggestion to run 'make check-c++' two ways,
 321 one with a new compiler and an old library, and the other with an old
 322 compiler and a new library, and look for testsuite regressions)
 323 </p><p>
 324 Details on how to set this kind of test up can be found here:
 325 http://gcc.gnu.org/ml/gcc/2002-08/msg00142.html
 326 </p><p>
 327 Two.
 328 Use the 'make check-abi' rule in the libstdc++ Makefile.
 329 </p><p>
 330 This is a proactive check the library ABI. Currently, exported symbol
 331 names that are either weak or defined are checked against a last known
 332 good baseline. Currently, this baseline is keyed off of 3.4.0
 333 binaries, as this was the last time the .so number was incremented. In
 334 addition, all exported names are demangled, and the exported objects
 335 are checked to make sure they are the same size as the same object in
 336 the baseline.
 337
 338 Notice that each baseline is relative to a <span class="emphasis"><em>default</em></span>
 339 configured library and compiler: in particular, if options such as
 340 --enable-clocale, or --with-cpu, in case of multilibs, are used at
 341 configure time, the check may fail, either because of substantive
 342 differences or because of limitations of the current checking
 343 machinery.
 344 </p><p>
 345 This dataset is insufficient, yet a start. Also needed is a
 346 comprehensive check for all user-visible types part of the standard
 347 library for sizeof() and alignof() changes.
 348 </p><p>
 349 Verifying compatible layouts of objects is not even attempted.  It
 350 should be possible to use sizeof, alignof, and offsetof to compute
 351 offsets for each structure and type in the standard library, saving to
 352 another datafile. Then, compute this in a similar way for new
 353 binaries, and look for differences.
 354 </p><p>
 355 Another approach might be to use the -fdump-class-hierarchy flag to
 356 get information. However, currently this approach gives insufficient
 357 data for use in library testing, as class data members, their offsets,
 358 and other detailed data is not displayed with this flag.
 359 (See g++/7470 on how this was used to find bugs.)
 360 </p><p>
 361 Perhaps there are other C++ ABI checkers. If so, please notify
 362 us. We'd like to know about them!
 363 </p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="abi.testing.multi"></a>Multiple ABI Testing</h4></div></div></div><p>
 364 A "C" application, dynamically linked to two shared libraries, liba,
 365 libb. The dependent library liba is C++ shared library compiled with
 366 gcc-3.3.x, and uses io, exceptions, locale, etc. The dependent library
 367 libb is a C++ shared library compiled with gcc-3.4.x, and also uses io,
 368 exceptions, locale, etc.
 369 </p><p> As above, libone is constructed as follows: </p><pre class="programlisting">
 370 %$bld/H-x86-gcc-3.4.0/bin/g++ -fPIC -DPIC -c a.cc
 371
 372 %$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
 373
 374 %ln -s libone.so.1.0.0 libone.so
 375
 376 %$bld/H-x86-gcc-3.4.0/bin/g++ -c a.cc
 377
 378 %ar cru libone.a a.o
 379 </pre><p> And, libtwo is constructed as follows: </p><pre class="programlisting">
 380 %$bld/H-x86-gcc-3.3.3/bin/g++ -fPIC -DPIC -c b.cc
 381
 382 %$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
 383
 384 %ln -s libtwo.so.1.0.0 libtwo.so
 385
 386 %$bld/H-x86-gcc-3.3.3/bin/g++ -c b.cc
 387
 388 %ar cru libtwo.a b.o
 389 </pre><p> ...with the resulting libraries looking like </p><pre class="screen">
 390 <code class="computeroutput">
 391 %ldd libone.so.1.0.0
 392         libstdc++.so.6 =&gt; /usr/lib/libstdc++.so.6 (0x40016000)
 393         libm.so.6 =&gt; /lib/tls/libm.so.6 (0x400fa000)
 394         libgcc_s.so.1 =&gt; /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x4011c000)
 395         libc.so.6 =&gt; /lib/tls/libc.so.6 (0x40125000)
 396         /lib/ld-linux.so.2 =&gt; /lib/ld-linux.so.2 (0x00355000)
 397
 398 %ldd libtwo.so.1.0.0
 399         libstdc++.so.5 =&gt; /usr/lib/libstdc++.so.5 (0x40027000)
 400         libm.so.6 =&gt; /lib/tls/libm.so.6 (0x400e1000)
 401         libgcc_s.so.1 =&gt; /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40103000)
 402         libc.so.6 =&gt; /lib/tls/libc.so.6 (0x4010c000)
 403         /lib/ld-linux.so.2 =&gt; /lib/ld-linux.so.2 (0x00355000)
 404 </code>
 405 </pre><p>
 406   Then, the "C" compiler is used to compile a source file that uses
 407   functions from each library.
 408 </p><pre class="programlisting">
 409 gcc test.c -g -O2 -L. -lone -ltwo /usr/lib/libstdc++.so.5 /usr/lib/libstdc++.so.6
 410 </pre><p>
 411   Which gives the expected:
 412 </p><pre class="screen">
 413 <code class="computeroutput">
 414 %ldd a.out
 415         libstdc++.so.5 =&gt; /usr/lib/libstdc++.so.5 (0x00764000)
 416         libstdc++.so.6 =&gt; /usr/lib/libstdc++.so.6 (0x40015000)
 417         libc.so.6 =&gt; /lib/tls/libc.so.6 (0x0036d000)
 418         libm.so.6 =&gt; /lib/tls/libm.so.6 (0x004a8000)
 419         libgcc_s.so.1 =&gt; /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x400e5000)
 420         /lib/ld-linux.so.2 =&gt; /lib/ld-linux.so.2 (0x00355000)
 421 </code>
 422 </pre><p>
 423   This resulting binary, when executed, will be able to safely use
 424   code from both liba, and the dependent libstdc++.so.6, and libb,
 425   with the dependent libstdc++.so.5.
 426 </p></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="abi.issues"></a>Outstanding Issues</h3></div></div></div><p>
 427   Some features in the C++ language make versioning especially
 428   difficult. In particular, compiler generated constructs such as
 429   implicit instantiations for templates, typeinfo information, and
 430   virtual tables all may cause ABI leakage across shared library
 431   boundaries. Because of this, mixing C++ ABIs is not recommended at
 432   this time.
 433 </p><p>
 434   For more background on this issue, see these bugzilla entries:
 435 </p><p>
 436 <a class="ulink" href="http://gcc.gnu.org/PR24660" target="_top">24660: versioning weak symbols in libstdc++</a>
 437 </p><p>
 438 <a class="ulink" href="http://gcc.gnu.org/PR19664" target="_top">19664: libstdc++ headers should have pop/push of the visibility around the declarations</a>
 439 </p></div><div class="bibliography"><div class="titlepage"><div><div><h3 class="title"><a id="abi.biblio"></a>Bibliography</h3></div></div></div><div class="biblioentry"><a id="id429530"></a><p><span class="title"><i>
 440       ABIcheck, a vague idea of checking ABI compatibility
 441     </i>. </span><span class="biblioid">
 442       <a class="ulink" href="http://abicheck.sourceforge.net/" target="_top">
 443       </a>
 444     . </span></p></div><div class="biblioentry"><a id="id429548"></a><p><span class="title"><i>
 445       C++ ABI Reference
 446     </i>. </span><span class="biblioid">
 447       <a class="ulink" href="http://www.codesourcery.com/cxx-abi" target="_top">
 448       </a>
 449     . </span></p></div><div class="biblioentry"><a id="id429565"></a><p><span class="title"><i>
 450       Intel® Compilers for Linux* -Compatibility with the GNU Compilers
 451     </i>. </span><span class="biblioid">
 452       <a class="ulink" href="http://developer.intel.com/software/products/compilers/techtopics/LinuxCompilersCompatibility.htm" target="_top">
 453       </a>
 454     . </span></p></div><div class="biblioentry"><a id="id429583"></a><p><span class="title"><i>
 455       Intel® Compilers for Linux* -Compatibility with the GNU Compilers
 456     </i>. </span><span class="biblioid">
 457       <a class="ulink" href="http://developer.intel.com/software/products/compilers/techtopics/LinuxCompilersCompatibility.htm" target="_top">
 458       </a>
 459     . </span></p></div><div class="biblioentry"><a id="id429600"></a><p><span class="title"><i>
 460       Sun Solaris 2.9 : Linker and Libraries Guide (document 816-1386)
 461     </i>. </span><span class="biblioid">
 462       <a class="ulink" href="http://docs.sun.com/?p=/doc/816-1386&amp;a=load" target="_top">
 463       </a>
 464     . </span></p></div><div class="biblioentry"><a id="id429617"></a><p><span class="title"><i>
 465       Sun Solaris 2.9 : C++ Migration Guide (document 816-2459)
 466     </i>. </span><span class="biblioid">
 467       <a class="ulink" href="http://docs.sun.com/db/prod/solaris.9" target="_top">
 468       </a>
 469     . </span></p></div><div class="biblioentry"><a id="id429635"></a><p><span class="title"><i>
 470       ELF Symbol Versioning
 471     </i>. </span><span class="author"><span class="firstname">Ulrich</span> <span class="surname">Drepper</span>. </span><span class="biblioid">
 472       <a class="ulink" href="http://people.redhat.com/drepper/symbol-versioning" target="_top">
 473       </a>
 474     . </span></p></div><div class="biblioentry"><a id="id429663"></a><p><span class="title"><i>
 475       C++ ABI for the ARM Architecture
 476     </i>. </span><span class="biblioid">
 477       <a class="ulink" href="http://www.arm.com/miscPDFs/8033.pdf" target="_top">
 478       </a>
 479     . </span></p></div><div class="biblioentry"><a id="id429680"></a><p><span class="title"><i>
 480       Dynamic Shared Objects: Survey and Issues
 481     </i>. </span><span class="subtitle">
 482       ISO C++ J16/06-0046
 483     . </span><span class="author"><span class="firstname">Benjamin</span> <span class="surname">Kosnik</span>. </span><span class="biblioid">
 484       <a class="ulink" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1976.html" target="_top">
 485       </a>
 486     . </span></p></div><div class="biblioentry"><a id="id497460"></a><p><span class="title"><i>
 487       Versioning With Namespaces
 488     </i>. </span><span class="subtitle">
 489       ISO C++ J16/06-0083
 490     . </span><span class="author"><span class="firstname">Benjamin</span> <span class="surname">Kosnik</span>. </span><span class="biblioid">
 491       <a class="ulink" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n2013.html" target="_top">
 492       </a>
 493     . </span></p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="internals.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendix_porting.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="api.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Porting to New Hardware or Operating Systems </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> API Evolution and Deprecation History</td></tr></table></div></body></html>