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

   1 <sect1 id="appendix.porting.abi" xreflabel="abi">
   2 <?dbhtml filename="abi.html"?>
   3
   4 <sect1info>
   5   <keywordset>
   6     <keyword>
   7       C++
   8     </keyword>
   9     <keyword>
  10       ABI
  11     </keyword>
  12     <keyword>
  13       version
  14     </keyword>
  15     <keyword>
  16       dynamic
  17     </keyword>
  18     <keyword>
  19       shared
  20     </keyword>
  21     <keyword>
  22       compatibility
  23     </keyword>
  24   </keywordset>
  25 </sect1info>
  26
  27 <title>ABI Policy and Guidelines</title>
  28
  29 <para>
  30 </para>
  31
  32 <sect2 id="abi.cxx_interface">
  33 <title>The C++ Interface</title>
  34
  35 <para>
  36   C++ applications often dependent on specific language support
  37   routines, say for throwing exceptions, or catching exceptions, and
  38   perhaps also dependent on features in the C++ Standard Library.
  39 </para>
  40
  41 <para>
  42   The C++ Standard Library has many include files, types defined in
  43   those include files, specific named functions, and other
  44   behavior. The text of these behaviors, as written in source include
  45   files, is called the Application Programing Interface, or API.
  46 </para>
  47
  48 <para>
  49   Furthermore, C++ source that is compiled into object files is
  50   transformed by the compiler: it arranges objects with specific
  51   alignment and in a particular layout, mangling names according to a
  52   well-defined algorithm, has specific arrangements for the support of
  53   virtual functions, etc. These details are defined as the compiler
  54   Application Binary Interface, or ABI. The GNU C++ compiler uses an
  55   industry-standard C++ ABI starting with version 3. Details can be
  56   found in the <ulink
  57   url="http://www.codesourcery.com/cxx-abi/abi.html"> ABI
  58   specification</ulink>.
  59 </para>
  60
  61 <para>
  62  The GNU C++ compiler, g++, has a compiler command line option to
  63   switch between various different C++ ABIs. This explicit version
  64   switch is the flag <code>-fabi-version</code>. In addition, some
  65   g++ command line options may change the ABI as a side-effect of
  66   use. Such flags include <code>-fpack-struct</code> and
  67   <code>-fno-exceptions</code>, but include others: see the complete
  68   list in the GCC manual under the heading <ulink url="http://gcc.gnu.org/onlinedocs/gcc/Code-Gen-Options.html#Code%20Gen%20Options">Options
  69   for Code Generation Conventions</ulink>.
  70 </para>
  71
  72 <para>
  73   The configure options used when building a specific libstdc++
  74   version may also impact the resulting library ABI. The available
  75   configure options, and their impact on the library ABI, are
  76   documented
  77 <link linkend="manual.intro.setup.configure">here</link>.
  78 </para>
  79
  80 <para> Putting all of these ideas together results in the C++ Standard
  81 library ABI, which is the compilation of a given library API by a
  82 given compiler ABI. In a nutshell:
  83 </para>
  84
  85 <para>
  86   <quote>
  87     library API + compiler ABI = library ABI
  88   </quote>
  89 </para>
  90
  91 <para>
  92  The library ABI is mostly of interest for end-users who have
  93  unresolved symbols and are linking dynamically to the C++ Standard
  94  library, and who thus must be careful to compile their application
  95  with a compiler that is compatible with the available C++ Standard
  96  library binary. In this case, compatible is defined with the equation
  97  above: given an application compiled with a given compiler ABI and
  98  library API, it will work correctly with a Standard C++ Library
  99  created with the same constraints.
 100 </para>
 101
 102 <para>
 103   To use a specific version of the C++ ABI, one must use a
 104   corresponding GNU C++ toolchain (i.e., g++ and libstdc++) that
 105   implements the C++ ABI in question.
 106 </para>
 107
 108 </sect2>
 109
 110 <sect2 id="abi.versioning">
 111 <title>Versioning</title>
 112
 113 <para> The C++ interface has evolved throughout the history of the GNU
 114 C++ toolchain. With each release, various details have been changed so
 115 as to give distinct versions to the C++ interface.
 116 </para>
 117
 118   <sect3 id="abi.versioning.goals">
 119     <title>Goals</title>
 120
 121 <para>Extending existing, stable ABIs. Versioning gives subsequent
 122 releases of library binaries the ability to add new symbols and add
 123 functionality, all the while retaining compatibility with the previous
 124 releases in the series. Thus, program binaries linked with the initial
 125 release of a library binary will still link correctly if the library
 126 binary is replaced by carefully-managed subsequent library
 127 binaries. This is called forward compatibility.
 128 </para>
 129 <para>
 130 The reverse (backwards compatibility) is not true. It is not possible
 131 to take program binaries linked with the latest version of a library
 132 binary in a release series (with additional symbols added), substitute
 133 in the initial release of the library binary, and remain link
 134 compatible.
 135 </para>
 136
 137 <para>Allows multiple, incompatible ABIs to coexist at the same time.
 138 </para>
 139   </sect3>
 140
 141   <sect3 id="abi.versioning.history">
 142     <title>History</title>
 143
 144 <para>
 145  How can this complexity be managed? What does C++ versioning mean?
 146   Because library and compiler changes often make binaries compiled
 147   with one version of the GNU tools incompatible with binaries
 148   compiled with other (either newer or older) versions of the same GNU
 149   tools, specific techniques are used to make managing this complexity
 150   easier.
 151 </para>
 152
 153 <para>
 154   The following techniques are used:
 155 </para>
 156
 157   <orderedlist>
 158
 159     <listitem><para>Release versioning on the libgcc_s.so binary. </para>
 160
 161     <para>This is implemented via file names and the ELF
 162     <constant>DT_SONAME</constant> mechanism (at least on ELF
 163     systems). It is versioned as follows:
 164     </para>
 165
 166     <itemizedlist>
 167     <listitem><para>gcc-3.0.0: libgcc_s.so.1</para></listitem>
 168     <listitem><para>gcc-3.0.1: libgcc_s.so.1</para></listitem>
 169     <listitem><para>gcc-3.0.2: libgcc_s.so.1</para></listitem>
 170     <listitem><para>gcc-3.0.3: libgcc_s.so.1</para></listitem>
 171     <listitem><para>gcc-3.0.4: libgcc_s.so.1</para></listitem>
 172     <listitem><para>gcc-3.1.0: libgcc_s.so.1</para></listitem>
 173     <listitem><para>gcc-3.1.1: libgcc_s.so.1</para></listitem>
 174     <listitem><para>gcc-3.2.0: libgcc_s.so.1</para></listitem>
 175     <listitem><para>gcc-3.2.1: libgcc_s.so.1</para></listitem>
 176     <listitem><para>gcc-3.2.2: libgcc_s.so.1</para></listitem>
 177     <listitem><para>gcc-3.2.3: libgcc_s.so.1</para></listitem>
 178     <listitem><para>gcc-3.3.0: libgcc_s.so.1</para></listitem>
 179     <listitem><para>gcc-3.3.1: libgcc_s.so.1</para></listitem>
 180     <listitem><para>gcc-3.3.2: libgcc_s.so.1</para></listitem>
 181     <listitem><para>gcc-3.3.3: libgcc_s.so.1</para></listitem>
 182     <listitem><para>gcc-3.4.x, gcc-4.[0-5].x: libgcc_s.so.1</para></listitem>
 183     </itemizedlist>
 184
 185     <para>For m68k-linux the versions differ as follows: </para>
 186
 187     <itemizedlist>
 188     <listitem><para>gcc-3.4.x, gcc-4.[0-5].x: libgcc_s.so.1
 189     when configuring <code>--with-sjlj-exceptions</code>, or
 190     libgcc_s.so.2 </para> </listitem>
 191     </itemizedlist>
 192
 193     <para>For hppa-linux the versions differ as follows: </para>
 194
 195     <itemizedlist>
 196     <listitem><para>gcc-3.4.x, gcc-4.[0-1].x: either libgcc_s.so.1
 197     when configuring <code>--with-sjlj-exceptions</code>, or
 198     libgcc_s.so.2 </para> </listitem>
 199     <listitem><para>gcc-4.[2-5].x: either libgcc_s.so.3 when configuring
 200     <code>--with-sjlj-exceptions</code>) or libgcc_s.so.4
 201     </para> </listitem>
 202     </itemizedlist>
 203
 204   </listitem>
 205
 206     <listitem><para>Symbol versioning on the libgcc_s.so binary.</para>
 207
 208     <para>It is versioned with the following labels and version
 209    definitions, where the version definition is the maximum for a
 210    particular release. Labels are cumulative. If a particular release
 211    is not listed, it has the same version labels as the preceding
 212    release.</para>
 213
 214     <para>This corresponds to the mapfile: gcc/libgcc-std.ver</para>
 215     <itemizedlist>
 216     <listitem><para>gcc-3.0.0: GCC_3.0</para></listitem>
 217     <listitem><para>gcc-3.3.0: GCC_3.3</para></listitem>
 218     <listitem><para>gcc-3.3.1: GCC_3.3.1</para></listitem>
 219     <listitem><para>gcc-3.3.2: GCC_3.3.2</para></listitem>
 220     <listitem><para>gcc-3.3.4: GCC_3.3.4</para></listitem>
 221     <listitem><para>gcc-3.4.0: GCC_3.4</para></listitem>
 222     <listitem><para>gcc-3.4.2: GCC_3.4.2</para></listitem>
 223     <listitem><para>gcc-3.4.4: GCC_3.4.4</para></listitem>
 224     <listitem><para>gcc-4.0.0: GCC_4.0.0</para></listitem>
 225     <listitem><para>gcc-4.1.0: GCC_4.1.0</para></listitem>
 226     <listitem><para>gcc-4.2.0: GCC_4.2.0</para></listitem>
 227     <listitem><para>gcc-4.3.0: GCC_4.3.0</para></listitem>
 228     <listitem><para>gcc-4.4.0: GCC_4.4.0</para></listitem>
 229     </itemizedlist>
 230     </listitem>
 231
 232     <listitem>
 233       <para>
 234         Release versioning on the libstdc++.so binary, implemented in
 235         the same was as the libgcc_s.so binary above. Listed is the
 236         filename: <constant>DT_SONAME</constant> can be deduced from
 237         the filename by removing the last two period-delimited numbers. For
 238         example, filename <filename>libstdc++.so.5.0.4</filename>
 239         corresponds to a <constant>DT_SONAME</constant> of
 240         <constant>libstdc++.so.5</constant>. Binaries with equivalent
 241         <constant>DT_SONAME</constant>s are forward-compatibile: in
 242         the table below, releases incompatible with the previous
 243         one are explicitly noted.
 244       </para>
 245
 246     <para>It is versioned as follows:
 247     </para>
 248     <itemizedlist>
 249     <listitem><para>gcc-3.0.0: libstdc++.so.3.0.0</para></listitem>
 250     <listitem><para>gcc-3.0.1: libstdc++.so.3.0.1</para></listitem>
 251     <listitem><para>gcc-3.0.2: libstdc++.so.3.0.2</para></listitem>
 252     <listitem><para>gcc-3.0.3: libstdc++.so.3.0.2 (See Note 1)</para></listitem>
 253     <listitem><para>gcc-3.0.4: libstdc++.so.3.0.4</para></listitem>
 254     <listitem><para>gcc-3.1.0: libstdc++.so.4.0.0 <emphasis>(Incompatible with previous)</emphasis></para></listitem>
 255     <listitem><para>gcc-3.1.1: libstdc++.so.4.0.1</para></listitem>
 256     <listitem><para>gcc-3.2.0: libstdc++.so.5.0.0 <emphasis>(Incompatible with previous)</emphasis></para></listitem>
 257     <listitem><para>gcc-3.2.1: libstdc++.so.5.0.1</para></listitem>
 258     <listitem><para>gcc-3.2.2: libstdc++.so.5.0.2</para></listitem>
 259     <listitem><para>gcc-3.2.3: libstdc++.so.5.0.3 (See Note 2)</para></listitem>
 260     <listitem><para>gcc-3.3.0: libstdc++.so.5.0.4</para></listitem>
 261     <listitem><para>gcc-3.3.1: libstdc++.so.5.0.5</para></listitem>
 262     <listitem><para>gcc-3.3.2: libstdc++.so.5.0.5</para></listitem>
 263     <listitem><para>gcc-3.3.3: libstdc++.so.5.0.5</para></listitem>
 264     <listitem><para>gcc-3.4.0: libstdc++.so.6.0.0 <emphasis>(Incompatible with previous)</emphasis></para></listitem>
 265     <listitem><para>gcc-3.4.1: libstdc++.so.6.0.1</para></listitem>
 266     <listitem><para>gcc-3.4.2: libstdc++.so.6.0.2</para></listitem>
 267     <listitem><para>gcc-3.4.3: libstdc++.so.6.0.3</para></listitem>
 268     <listitem><para>gcc-3.4.4: libstdc++.so.6.0.3</para></listitem>
 269     <listitem><para>gcc-3.4.5: libstdc++.so.6.0.3</para></listitem>
 270     <listitem><para>gcc-3.4.6: libstdc++.so.6.0.3</para></listitem>
 271     <listitem><para>gcc-4.0.0: libstdc++.so.6.0.4</para></listitem>
 272     <listitem><para>gcc-4.0.1: libstdc++.so.6.0.5</para></listitem>
 273     <listitem><para>gcc-4.0.2: libstdc++.so.6.0.6</para></listitem>
 274     <listitem><para>gcc-4.0.3: libstdc++.so.6.0.7</para></listitem>
 275     <listitem><para>gcc-4.1.0: libstdc++.so.6.0.7</para></listitem>
 276     <listitem><para>gcc-4.1.1: libstdc++.so.6.0.8</para></listitem>
 277     <listitem><para>gcc-4.1.2: libstdc++.so.6.0.8</para></listitem>
 278     <listitem><para>gcc-4.2.0: libstdc++.so.6.0.9</para></listitem>
 279     <listitem><para>gcc-4.2.1: libstdc++.so.6.0.9 (See Note 3)</para></listitem>
 280     <listitem><para>gcc-4.2.2: libstdc++.so.6.0.9</para></listitem>
 281     <listitem><para>gcc-4.2.3: libstdc++.so.6.0.9</para></listitem>
 282     <listitem><para>gcc-4.2.4: libstdc++.so.6.0.9</para></listitem>
 283     <listitem><para>gcc-4.3.0: libstdc++.so.6.0.10</para></listitem>
 284     <listitem><para>gcc-4.3.1: libstdc++.so.6.0.10</para></listitem>
 285     <listitem><para>gcc-4.3.2: libstdc++.so.6.0.10</para></listitem>
 286     <listitem><para>gcc-4.3.3: libstdc++.so.6.0.10</para></listitem>
 287     <listitem><para>gcc-4.3.4: libstdc++.so.6.0.10</para></listitem>
 288     <listitem><para>gcc-4.4.0: libstdc++.so.6.0.11</para></listitem>
 289     <listitem><para>gcc-4.4.1: libstdc++.so.6.0.12</para></listitem>
 290     <listitem><para>gcc-4.4.2: libstdc++.so.6.0.13</para></listitem>
 291     <listitem><para>gcc-4.5.0: libstdc++.so.6.0.14</para></listitem>
 292     </itemizedlist>
 293     <para>
 294       Note 1: Error should be libstdc++.so.3.0.3.
 295     </para>
 296     <para>
 297       Note 2: Not strictly required.
 298     </para>
 299     <para>
 300       Note 3: This release (but not previous or subsequent) has one
 301       known incompatibility, see <ulink
 302       url="http://gcc.gnu.org/bugzilla/show_bug.cgi?id=33678">33678</ulink>
 303       in the GCC bug database.
 304     </para>
 305     </listitem>
 306
 307     <listitem><para>Symbol versioning on the libstdc++.so binary.</para>
 308
 309     <para>mapfile: libstdc++/config/linker-map.gnu</para>
 310     <para>It is versioned with the following labels and version
 311    definitions, where the version definition is the maximum for a
 312    particular release. Note, only symbol which are newly introduced
 313    will use the maximum version definition. Thus, for release series
 314    with the same label, but incremented version definitions, the later
 315    release has both versions. (An example of this would be the
 316    gcc-3.2.1 release, which has GLIBCPP_3.2.1 for new symbols and
 317    GLIBCPP_3.2 for symbols that were introduced in the gcc-3.2.0
 318    release.) If a particular release is not listed, it has the same
 319    version labels as the preceding release.
 320    </para>
 321     <itemizedlist>
 322     <listitem><para>gcc-3.0.0: (Error, not versioned)</para></listitem>
 323     <listitem><para>gcc-3.0.1: (Error, not versioned)</para></listitem>
 324     <listitem><para>gcc-3.0.2: (Error, not versioned)</para></listitem>
 325     <listitem><para>gcc-3.0.3: (Error, not versioned)</para></listitem>
 326     <listitem><para>gcc-3.0.4: (Error, not versioned)</para></listitem>
 327     <listitem><para>gcc-3.1.0: GLIBCPP_3.1, CXXABI_1</para></listitem>
 328     <listitem><para>gcc-3.1.1: GLIBCPP_3.1, CXXABI_1</para></listitem>
 329     <listitem><para>gcc-3.2.0: GLIBCPP_3.2, CXXABI_1.2</para></listitem>
 330     <listitem><para>gcc-3.2.1: GLIBCPP_3.2.1, CXXABI_1.2</para></listitem>
 331     <listitem><para>gcc-3.2.2: GLIBCPP_3.2.2, CXXABI_1.2</para></listitem>
 332     <listitem><para>gcc-3.2.3: GLIBCPP_3.2.2, CXXABI_1.2</para></listitem>
 333     <listitem><para>gcc-3.3.0: GLIBCPP_3.2.2, CXXABI_1.2.1</para></listitem>
 334     <listitem><para>gcc-3.3.1: GLIBCPP_3.2.3, CXXABI_1.2.1</para></listitem>
 335     <listitem><para>gcc-3.3.2: GLIBCPP_3.2.3, CXXABI_1.2.1</para></listitem>
 336     <listitem><para>gcc-3.3.3: GLIBCPP_3.2.3, CXXABI_1.2.1</para></listitem>
 337     <listitem><para>gcc-3.4.0: GLIBCXX_3.4, CXXABI_1.3</para></listitem>
 338     <listitem><para>gcc-3.4.1: GLIBCXX_3.4.1, CXXABI_1.3</para></listitem>
 339     <listitem><para>gcc-3.4.2: GLIBCXX_3.4.2</para></listitem>
 340     <listitem><para>gcc-3.4.3: GLIBCXX_3.4.3</para></listitem>
 341     <listitem><para>gcc-4.0.0: GLIBCXX_3.4.4, CXXABI_1.3.1</para></listitem>
 342     <listitem><para>gcc-4.0.1: GLIBCXX_3.4.5</para></listitem>
 343     <listitem><para>gcc-4.0.2: GLIBCXX_3.4.6</para></listitem>
 344     <listitem><para>gcc-4.0.3: GLIBCXX_3.4.7</para></listitem>
 345     <listitem><para>gcc-4.1.1: GLIBCXX_3.4.8</para></listitem>
 346     <listitem><para>gcc-4.2.0: GLIBCXX_3.4.9</para></listitem>
 347     <listitem><para>gcc-4.3.0: GLIBCXX_3.4.10, CXXABI_1.3.2</para></listitem>
 348     <listitem><para>gcc-4.4.0: GLIBCXX_3.4.11, CXXABI_1.3.3</para></listitem>
 349     <listitem><para>gcc-4.4.1: GLIBCXX_3.4.12, CXXABI_1.3.3</para></listitem>
 350     <listitem><para>gcc-4.4.2: GLIBCXX_3.4.13, CXXABI_1.3.3</para></listitem>
 351     <listitem><para>gcc-4.5.0: GLIBCXX_3.4.14, CXXABI_1.3.4</para></listitem>
 352     </itemizedlist>
 353     </listitem>
 354
 355     <listitem>
 356     <para>Incremental bumping of a compiler pre-defined macro,
 357     __GXX_ABI_VERSION. This macro is defined as the version of the
 358     compiler v3 ABI, with g++ 3.0.x being version 100. This macro will
 359     be automatically defined whenever g++ is used (the curious can
 360     test this by invoking g++ with the '-v' flag.)
 361     </para>
 362
 363     <para>
 364     This macro was defined in the file "lang-specs.h" in the gcc/cp directory.
 365     Later versions defined it in "c-common.c" in the gcc directory, and from
 366     G++ 3.4 it is defined in c-cppbuiltin.c and its value determined by the
 367     '-fabi-version' command line option.
 368     </para>
 369
 370     <para>
 371     It is versioned as follows, where 'n' is given by '-fabi-version=n':
 372     </para>
 373     <itemizedlist>
 374     <listitem><para>gcc-3.0.x: 100</para></listitem>
 375     <listitem><para>gcc-3.1.x: 100 (Error, should be 101)</para></listitem>
 376     <listitem><para>gcc-3.2.x: 102</para></listitem>
 377     <listitem><para>gcc-3.3.x: 102</para></listitem>
 378     <listitem><para>gcc-3.4.x, gcc-4.[0-5].x: 102 (when n=1)</para></listitem>
 379     <listitem><para>gcc-3.4.x, gcc-4.[0-5].x: 1000 + n (when n&gt;1) </para></listitem>
 380     <listitem><para>gcc-3.4.x, gcc-4.[0-5].x: 999999 (when n=0)</para></listitem>
 381     </itemizedlist>
 382     <para></para>
 383     </listitem>
 384
 385     <listitem>
 386     <para>Changes to the default compiler option for
 387     <code>-fabi-version</code>.
 388     </para>
 389    <para>
 390     It is versioned as follows:
 391     </para>
 392     <itemizedlist>
 393     <listitem><para>gcc-3.0.x: (Error, not versioned) </para></listitem>
 394     <listitem><para>gcc-3.1.x: (Error, not versioned) </para></listitem>
 395     <listitem><para>gcc-3.2.x: <code>-fabi-version=1</code></para></listitem>
 396     <listitem><para>gcc-3.3.x: <code>-fabi-version=1</code></para></listitem>
 397     <listitem><para>gcc-3.4.x, gcc-4.[0-5].x: <code>-fabi-version=2</code> <emphasis>(Incompatible with previous)</emphasis></para></listitem>
 398     </itemizedlist>
 399     <para></para>
 400     </listitem>
 401
 402    <listitem>
 403     <para>Incremental bumping of a library pre-defined macro. For releases
 404     before 3.4.0, the macro is __GLIBCPP__. For later releases, it's
 405     __GLIBCXX__. (The libstdc++ project generously changed from CPP to
 406     CXX throughout its source to allow the "C" pre-processor the CPP
 407     macro namespace.) These macros are defined as the date the library
 408     was released, in compressed ISO date format, as an unsigned long.
 409     </para>
 410
 411     <para>
 412     This macro is defined in the file "c++config" in the
 413     "libstdc++/include/bits" directory. (Up to gcc-4.1.0, it was
 414     changed every night by an automated script. Since gcc-4.1.0, it is
 415     the same value as gcc/DATESTAMP.)
 416     </para>
 417     <para>
 418     It is versioned as follows:
 419     </para>
 420     <itemizedlist>
 421     <listitem><para>gcc-3.0.0: 20010615</para></listitem>
 422     <listitem><para>gcc-3.0.1: 20010819</para></listitem>
 423     <listitem><para>gcc-3.0.2: 20011023</para></listitem>
 424     <listitem><para>gcc-3.0.3: 20011220</para></listitem>
 425     <listitem><para>gcc-3.0.4: 20020220</para></listitem>
 426     <listitem><para>gcc-3.1.0: 20020514</para></listitem>
 427     <listitem><para>gcc-3.1.1: 20020725</para></listitem>
 428     <listitem><para>gcc-3.2.0: 20020814</para></listitem>
 429     <listitem><para>gcc-3.2.1: 20021119</para></listitem>
 430     <listitem><para>gcc-3.2.2: 20030205</para></listitem>
 431     <listitem><para>gcc-3.2.3: 20030422</para></listitem>
 432     <listitem><para>gcc-3.3.0: 20030513</para></listitem>
 433     <listitem><para>gcc-3.3.1: 20030804</para></listitem>
 434     <listitem><para>gcc-3.3.2: 20031016</para></listitem>
 435     <listitem><para>gcc-3.3.3: 20040214</para></listitem>
 436     <listitem><para>gcc-3.4.0: 20040419</para></listitem>
 437     <listitem><para>gcc-3.4.1: 20040701</para></listitem>
 438     <listitem><para>gcc-3.4.2: 20040906</para></listitem>
 439     <listitem><para>gcc-3.4.3: 20041105</para></listitem>
 440     <listitem><para>gcc-3.4.4: 20050519</para></listitem>
 441     <listitem><para>gcc-3.4.5: 20051201</para></listitem>
 442     <listitem><para>gcc-3.4.6: 20060306</para></listitem>
 443     <listitem><para>gcc-4.0.0: 20050421</para></listitem>
 444     <listitem><para>gcc-4.0.1: 20050707</para></listitem>
 445     <listitem><para>gcc-4.0.2: 20050921</para></listitem>
 446     <listitem><para>gcc-4.0.3: 20060309</para></listitem>
 447     <listitem><para>gcc-4.1.0: 20060228</para></listitem>
 448     <listitem><para>gcc-4.1.1: 20060524</para></listitem>
 449     <listitem><para>gcc-4.1.2: 20070214</para></listitem>
 450     <listitem><para>gcc-4.2.0: 20070514</para></listitem>
 451     <listitem><para>gcc-4.2.1: 20070719</para></listitem>
 452     <listitem><para>gcc-4.2.2: 20071007</para></listitem>
 453     <listitem><para>gcc-4.2.3: 20080201</para></listitem>
 454     <listitem><para>gcc-4.2.4: 20080519</para></listitem>
 455     <listitem><para>gcc-4.3.0: 20080306</para></listitem>
 456     <listitem><para>gcc-4.3.1: 20080606</para></listitem>
 457     <listitem><para>gcc-4.3.2: 20080827</para></listitem>
 458     <listitem><para>gcc-4.3.3: 20090124</para></listitem>
 459     <listitem><para>gcc-4.4.0: 20090421</para></listitem>
 460     <listitem><para>gcc-4.4.1: 20090722</para></listitem>
 461     <listitem><para>gcc-4.4.2: 20091015</para></listitem>
 462     </itemizedlist>
 463     <para></para>
 464     </listitem>
 465
 466     <listitem>
 467     <para>
 468     Incremental bumping of a library pre-defined macro,
 469     _GLIBCPP_VERSION. This macro is defined as the released version of
 470     the library, as a string literal. This is only implemented in
 471     gcc-3.1.0 releases and higher, and is deprecated in 3.4 (where it
 472     is called _GLIBCXX_VERSION).
 473     </para>
 474
 475     <para>
 476     This macro is defined in the file "c++config" in the
 477     "libstdc++/include/bits" directory and is generated
 478     automatically by autoconf as part of the configure-time generation
 479     of config.h.
 480     </para>
 481
 482     <para>
 483     It is versioned as follows:
 484     </para>
 485     <itemizedlist>
 486     <listitem><para>gcc-3.0.0: "3.0.0"</para></listitem>
 487     <listitem><para>gcc-3.0.1: "3.0.0" (Error, should be "3.0.1")</para></listitem>
 488     <listitem><para>gcc-3.0.2: "3.0.0" (Error, should be "3.0.2")</para></listitem>
 489     <listitem><para>gcc-3.0.3: "3.0.0" (Error, should be "3.0.3")</para></listitem>
 490     <listitem><para>gcc-3.0.4: "3.0.0" (Error, should be "3.0.4")</para></listitem>
 491     <listitem><para>gcc-3.1.0: "3.1.0"</para></listitem>
 492     <listitem><para>gcc-3.1.1: "3.1.1"</para></listitem>
 493     <listitem><para>gcc-3.2.0: "3.2"</para></listitem>
 494     <listitem><para>gcc-3.2.1: "3.2.1"</para></listitem>
 495     <listitem><para>gcc-3.2.2: "3.2.2"</para></listitem>
 496     <listitem><para>gcc-3.2.3: "3.2.3"</para></listitem>
 497     <listitem><para>gcc-3.3.0: "3.3"</para></listitem>
 498     <listitem><para>gcc-3.3.1: "3.3.1"</para></listitem>
 499     <listitem><para>gcc-3.3.2: "3.3.2"</para></listitem>
 500     <listitem><para>gcc-3.3.3: "3.3.3"</para></listitem>
 501     <listitem><para>gcc-3.4.x: "version-unused"</para></listitem>
 502     <listitem><para>gcc-4.[0-5].x: "version-unused"</para></listitem>
 503     </itemizedlist>
 504     <para></para>
 505     </listitem>
 506
 507     <listitem>
 508     <para>
 509     Matching each specific C++ compiler release to a specific set of
 510     C++ include files. This is only implemented in gcc-3.1.1 releases
 511     and higher.
 512     </para>
 513     <para>
 514     All C++ includes are installed in include/c++, then nest in a
 515     directory hierarchy corresponding to the C++ compiler's released
 516     version. This version corresponds to the variable "gcc_version" in
 517     "libstdc++/acinclude.m4," and more details can be found in that
 518     file's macro GLIBCXX_CONFIGURE (GLIBCPP_CONFIGURE before gcc-3.4.0).
 519     </para>
 520     <para>
 521     C++ includes are versioned as follows:
 522     </para>
 523     <itemizedlist>
 524     <listitem><para>gcc-3.0.0: include/g++-v3</para></listitem>
 525     <listitem><para>gcc-3.0.1: include/g++-v3</para></listitem>
 526     <listitem><para>gcc-3.0.2: include/g++-v3</para></listitem>
 527     <listitem><para>gcc-3.0.3: include/g++-v3</para></listitem>
 528     <listitem><para>gcc-3.0.4: include/g++-v3</para></listitem>
 529     <listitem><para>gcc-3.1.0: include/g++-v3</para></listitem>
 530     <listitem><para>gcc-3.1.1: include/c++/3.1.1</para></listitem>
 531     <listitem><para>gcc-3.2.0: include/c++/3.2</para></listitem>
 532     <listitem><para>gcc-3.2.1: include/c++/3.2.1</para></listitem>
 533     <listitem><para>gcc-3.2.2: include/c++/3.2.2</para></listitem>
 534     <listitem><para>gcc-3.2.3: include/c++/3.2.3</para></listitem>
 535     <listitem><para>gcc-3.3.0: include/c++/3.3</para></listitem>
 536     <listitem><para>gcc-3.3.1: include/c++/3.3.1</para></listitem>
 537     <listitem><para>gcc-3.3.2: include/c++/3.3.2</para></listitem>
 538     <listitem><para>gcc-3.3.3: include/c++/3.3.3</para></listitem>
 539     <listitem><para>gcc-3.4.0: include/c++/3.4.0</para></listitem>
 540     <listitem><para>gcc-3.4.1: include/c++/3.4.1</para></listitem>
 541     <listitem><para>gcc-3.4.2: include/c++/3.4.2</para></listitem>
 542     <listitem><para>gcc-3.4.3: include/c++/3.4.3</para></listitem>
 543     <listitem><para>gcc-3.4.4: include/c++/3.4.4</para></listitem>
 544     <listitem><para>gcc-3.4.5: include/c++/3.4.5</para></listitem>
 545     <listitem><para>gcc-3.4.6: include/c++/3.4.6</para></listitem>
 546     <listitem><para>gcc-4.0.0: include/c++/4.0.0</para></listitem>
 547     <listitem><para>gcc-4.0.1: include/c++/4.0.1</para></listitem>
 548     <listitem><para>gcc-4.0.2: include/c++/4.0.2</para></listitem>
 549     <listitem><para>gcc-4.0.3: include/c++/4.0.3</para></listitem>
 550     <listitem><para>gcc-4.1.0: include/c++/4.1.0</para></listitem>
 551     <listitem><para>gcc-4.1.1: include/c++/4.1.1</para></listitem>
 552     <listitem><para>gcc-4.1.2: include/c++/4.1.2</para></listitem>
 553     <listitem><para>gcc-4.2.0: include/c++/4.2.0</para></listitem>
 554     <listitem><para>gcc-4.2.1: include/c++/4.2.1</para></listitem>
 555     <listitem><para>gcc-4.2.2: include/c++/4.2.2</para></listitem>
 556     <listitem><para>gcc-4.2.3: include/c++/4.2.3</para></listitem>
 557     <listitem><para>gcc-4.2.4: include/c++/4.2.4</para></listitem>
 558     <listitem><para>gcc-4.3.0: include/c++/4.3.0</para></listitem>
 559     <listitem><para>gcc-4.3.1: include/c++/4.3.1</para></listitem>
 560     <listitem><para>gcc-4.3.3: include/c++/4.3.3</para></listitem>
 561     <listitem><para>gcc-4.3.4: include/c++/4.3.4</para></listitem>
 562     <listitem><para>gcc-4.4.0: include/c++/4.4.0</para></listitem>
 563     <listitem><para>gcc-4.4.1: include/c++/4.4.1</para></listitem>
 564     <listitem><para>gcc-4.4.2: include/c++/4.4.2</para></listitem>
 565     <listitem><para>gcc-4.5.0: include/c++/4.5.0</para></listitem>
 566     </itemizedlist>
 567     <para></para>
 568     </listitem>
 569   </orderedlist>
 570
 571 <para>
 572   Taken together, these techniques can accurately specify interface
 573   and implementation changes in the GNU C++ tools themselves. Used
 574   properly, they allow both the GNU C++ tools implementation, and
 575   programs using them, an evolving yet controlled development that
 576   maintains backward compatibility.
 577 </para>
 578
 579
 580   </sect3>
 581
 582   <sect3 id="abi.versioning.prereq">
 583     <title>Prerequisites</title>
 584     <para>
 585       Minimum environment that supports a versioned ABI: A supported
 586       dynamic linker, a GNU linker of sufficient vintage to understand
 587       demangled C++ name globbing (ld), a shared executable compiled
 588       with g++, and shared libraries (libgcc_s, libstdc++) compiled by
 589       a compiler (g++) with a compatible ABI. Phew.
 590     </para>
 591
 592     <para>
 593       On top of all that, an additional constraint: libstdc++ did not
 594       attempt to version symbols (or age gracefully, really) until
 595       version 3.1.0.
 596     </para>
 597
 598     <para>
 599       Most modern Linux and BSD versions, particularly ones using
 600       gcc-3.1.x tools and more recent vintages, will meet the
 601       requirements above.
 602     </para>
 603   </sect3>
 604
 605   <sect3 id="abi.versioning.config">
 606     <title>Configuring</title>
 607
 608     <para>
 609       It turns out that most of the configure options that change
 610       default behavior will impact the mangled names of exported
 611       symbols, and thus impact versioning and compatibility.
 612     </para>
 613
 614     <para>
 615       For more information on configure options, including ABI
 616       impacts, see:
 617       http://gcc.gnu.org/onlinedocs/libstdc++/configopts.html
 618     </para>
 619
 620     <para>
 621       There is one flag that explicitly deals with symbol versioning:
 622       --enable-symvers.
 623     </para>
 624
 625     <para>
 626       In particular, libstdc++/acinclude.m4 has a macro called
 627       GLIBCXX_ENABLE_SYMVERS that defaults to yes (or the argument
 628       passed in via --enable-symvers=foo). At that point, the macro
 629       attempts to make sure that all the requirement for symbol
 630       versioning are in place. For more information, please consult
 631       acinclude.m4.
 632     </para>
 633   </sect3>
 634
 635   <sect3 id="abi.versioning.active">
 636     <title>Checking Active</title>
 637
 638     <para>
 639       When the GNU C++ library is being built with symbol versioning
 640       on, you should see the following at configure time for
 641       libstdc++:
 642     </para>
 643
 644 <screen>
 645 <computeroutput>
 646   checking versioning on shared library symbols... gnu
 647 </computeroutput>
 648 </screen>
 649
 650 <para>
 651   If you don't see this line in the configure output, or if this line
 652   appears but the last word is 'no', then you are out of luck.
 653 </para>
 654
 655 <para>
 656   If the compiler is pre-installed, a quick way to test is to compile
 657   the following (or any) simple C++ file and link it to the shared
 658   libstdc++ library:
 659 </para>
 660
 661 <programlisting>
 662 #include &lt;iostream&gt;
 663
 664 int main()
 665 { std::cout &lt;&lt; "hello" &lt;&lt; std::endl; return 0; }
 666
 667 %g++ hello.cc -o hello.out
 668
 669 %ldd hello.out
 670         libstdc++.so.5 =&gt; /usr/lib/libstdc++.so.5 (0x00764000)
 671         libm.so.6 =&gt; /lib/tls/libm.so.6 (0x004a8000)
 672         libgcc_s.so.1 =&gt; /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40016000)
 673         libc.so.6 =&gt; /lib/tls/libc.so.6 (0x0036d000)
 674         /lib/ld-linux.so.2 =&gt; /lib/ld-linux.so.2 (0x00355000)
 675
 676 %nm hello.out
 677 </programlisting>
 678
 679 <para>
 680 If you see symbols in the resulting output with "GLIBCXX_3" as part
 681 of the name, then the executable is versioned. Here's an example:
 682 </para>
 683
 684 <para>
 685    <code>U _ZNSt8ios_base4InitC1Ev@@GLIBCXX_3.4</code>
 686 </para>
 687
 688   </sect3>
 689 </sect2>
 690
 691 <sect2 id="abi.changes_allowed">
 692 <title>Allowed Changes</title>
 693
 694 <para>
 695 The following will cause the library minor version number to
 696 increase, say from "libstdc++.so.3.0.4" to "libstdc++.so.3.0.5".
 697 </para>
 698 <orderedlist>
 699  <listitem><para>Adding an exported global or static data member</para></listitem>
 700  <listitem><para>Adding an exported function, static or non-virtual member function</para></listitem>
 701  <listitem><para>Adding an exported symbol or symbols by additional instantiations</para></listitem>
 702 </orderedlist>
 703 <para>
 704 Other allowed changes are possible.
 705 </para>
 706
 707 </sect2>
 708
 709 <sect2 id="abi.changes_no">
 710 <title>Prohibited Changes</title>
 711
 712 <para>
 713 The following non-exhaustive list will cause the library major version
 714 number to increase, say from "libstdc++.so.3.0.4" to
 715 "libstdc++.so.4.0.0".
 716 </para>
 717
 718 <orderedlist>
 719  <listitem><para>Changes in the gcc/g++ compiler ABI</para></listitem>
 720 <listitem><para>Changing size of an exported symbol</para></listitem>
 721 <listitem><para>Changing alignment of an exported symbol</para></listitem>
 722 <listitem><para>Changing the layout of an exported symbol</para></listitem>
 723 <listitem><para>Changing mangling on an exported symbol</para></listitem>
 724 <listitem><para>Deleting an exported symbol</para></listitem>
 725 <listitem><para>Changing the inheritance properties of a type by adding or removing
 726     base classes</para></listitem>
 727 <listitem><para>
 728   Changing the size, alignment, or layout of types
 729   specified in the C++ standard. These may not necessarily be
 730   instantiated or otherwise exported in the library binary, and
 731   include all the required locale facets, as well as things like
 732   std::basic_streambuf, et al.
 733 </para></listitem>
 734
 735 <listitem><para> Adding an explicit copy constructor or destructor to a
 736 class that would otherwise have implicit versions. This will change
 737 the way the compiler deals with this class in by-value return
 738 statements or parameters: instead of being passing instances of this
 739 class in registers, the compiler will be forced to use memory. See <ulink url="http://www.codesourcery.com/cxx-abi/abi.html#calls"> this part</ulink>
 740  of the C++ ABI documentation for further details.
 741  </para></listitem>
 742
 743 </orderedlist>
 744
 745 </sect2>
 746
 747
 748
 749 <sect2 id="abi.impl">
 750 <title>Implementation</title>
 751
 752 <orderedlist>
 753  <listitem>
 754    <para>
 755      Separation of interface and implementation
 756    </para>
 757    <para>
 758      This is accomplished by two techniques that separate the API from
 759      the ABI: forcing undefined references to link against a library
 760      binary for definitions.
 761    </para>
 762
 763 <variablelist>
 764   <varlistentry>
 765     <term>Include files have declarations, source files have defines</term>
 766
 767     <listitem>
 768       <para>
 769         For non-templatized types, such as much of <code>class
 770         locale</code>, the appropriate standard C++ include, say
 771         <code>locale</code>, can contain full declarations, while
 772         various source files (say <code> locale.cc, locale_init.cc,
 773         localename.cc</code>) contain definitions.
 774       </para>
 775     </listitem>
 776   </varlistentry>
 777
 778   <varlistentry>
 779   <term>Extern template on required types</term>
 780
 781    <listitem>
 782      <para>
 783        For parts of the standard that have an explicit list of
 784        required instantiations, the GNU extension syntax <code> extern
 785        template </code> can be used to control where template
 786        definitions reside. By marking required instantiations as
 787        <code> extern template </code> in include files, and providing
 788        explicit instantiations in the appropriate instantiation files,
 789        non-inlined template functions can be versioned. This technique
 790        is mostly used on parts of the standard that require <code>
 791        char</code> and <code> wchar_t</code> instantiations, and
 792        includes <code> basic_string</code>, the locale facets, and the
 793        types in <code> iostreams</code>.
 794      </para>
 795    </listitem>
 796   </varlistentry>
 797
 798  </variablelist>
 799
 800  <para>
 801    In addition, these techniques have the additional benefit that they
 802    reduce binary size, which can increase runtime performance.
 803  </para>
 804  </listitem>
 805
 806  <listitem>
 807    <para>
 808      Namespaces linking symbol definitions to export mapfiles
 809    </para>
 810    <para>
 811      All symbols in the shared library binary are processed by a
 812      linker script at build time that either allows or disallows
 813      external linkage. Because of this, some symbols, regardless of
 814      normal C/C++ linkage, are not visible. Symbols that are internal
 815      have several appealing characteristics: by not exporting the
 816      symbols, there are no relocations when the shared library is
 817      started and thus this makes for faster runtime loading
 818      performance by the underlying dynamic loading mechanism. In
 819      addition, they have the possibility of changing without impacting
 820      ABI compatibility.
 821    </para>
 822
 823 <para>The following namespaces are transformed by the mapfile:</para>
 824
 825 <variablelist>
 826
 827   <varlistentry>
 828 <term><code>namespace std</code></term>
 829 <listitem><para> Defaults to exporting all symbols in label
 830 <code>GLIBCXX</code> that do not begin with an underscore, i.e.,
 831 <code>__test_func</code> would not be exported by default. Select
 832 exceptional symbols are allowed to be visible.</para></listitem>
 833   </varlistentry>
 834
 835   <varlistentry>
 836 <term><code>namespace __gnu_cxx</code></term>
 837 <listitem><para> Defaults to not exporting any symbols in label
 838 <code>GLIBCXX</code>, select items are allowed to be visible.</para></listitem>
 839   </varlistentry>
 840
 841   <varlistentry>
 842 <term><code>namespace __gnu_internal</code></term>
 843 <listitem><para> Defaults to not exported, no items are allowed to be visible.</para></listitem>
 844   </varlistentry>
 845
 846   <varlistentry>
 847 <term><code>namespace __cxxabiv1</code>, aliased to <code> namespace abi</code></term>
 848 <listitem><para> Defaults to not exporting any symbols in label
 849 <code>CXXABI</code>, select items are allowed to be visible.</para></listitem>
 850   </varlistentry>
 851
 852 </variablelist>
 853 <para>
 854 </para>
 855 </listitem>
 856
 857  <listitem><para>Freezing the API</para>
 858  <para>Disallowed changes, as above, are not made on a stable release
 859 branch. Enforcement tends to be less strict with GNU extensions that
 860 standard includes.</para>
 861 </listitem>
 862 </orderedlist>
 863
 864 </sect2>
 865
 866 <sect2 id="abi.testing">
 867 <title>Testing</title>
 868
 869   <sect3 id="abi.testing.single">
 870     <title>Single ABI Testing</title>
 871
 872     <para>
 873       Testing for GNU C++ ABI changes is composed of two distinct
 874       areas: testing the C++ compiler (g++) for compiler changes, and
 875       testing the C++ library (libstdc++) for library changes.
 876     </para>
 877
 878     <para>
 879       Testing the C++ compiler ABI can be done various ways.
 880     </para>
 881
 882     <para>
 883       One.  Intel ABI checker.
 884     </para>
 885
 886 <para>
 887 Two.
 888 The second is yet unreleased, but has been announced on the gcc
 889 mailing list. It is yet unspecified if these tools will be freely
 890 available, and able to be included in a GNU project. Please contact
 891 Mark Mitchell (mark@codesourcery.com) for more details, and current
 892 status.
 893 </para>
 894
 895 <para>
 896 Three.
 897 Involves using the vlad.consistency test framework. This has also been
 898 discussed on the gcc mailing lists.
 899 </para>
 900
 901 <para>
 902 Testing the C++ library ABI can also be done various ways.
 903 </para>
 904
 905 <para>
 906 One.
 907 (Brendan Kehoe, Jeff Law suggestion to run 'make check-c++' two ways,
 908 one with a new compiler and an old library, and the other with an old
 909 compiler and a new library, and look for testsuite regressions)
 910 </para>
 911
 912 <para>
 913 Details on how to set this kind of test up can be found here:
 914 http://gcc.gnu.org/ml/gcc/2002-08/msg00142.html
 915 </para>
 916
 917 <para>
 918 Two.
 919 Use the 'make check-abi' rule in the libstdc++ Makefile.
 920 </para>
 921
 922 <para>
 923 This is a proactive check the library ABI. Currently, exported symbol
 924 names that are either weak or defined are checked against a last known
 925 good baseline. Currently, this baseline is keyed off of 3.4.0
 926 binaries, as this was the last time the .so number was incremented. In
 927 addition, all exported names are demangled, and the exported objects
 928 are checked to make sure they are the same size as the same object in
 929 the baseline.
 930
 931 Notice that each baseline is relative to a <emphasis>default</emphasis>
 932 configured library and compiler: in particular, if options such as
 933 --enable-clocale, or --with-cpu, in case of multilibs, are used at
 934 configure time, the check may fail, either because of substantive
 935 differences or because of limitations of the current checking
 936 machinery.
 937 </para>
 938
 939 <para>
 940 This dataset is insufficient, yet a start. Also needed is a
 941 comprehensive check for all user-visible types part of the standard
 942 library for sizeof() and alignof() changes.
 943 </para>
 944
 945 <para>
 946 Verifying compatible layouts of objects is not even attempted.  It
 947 should be possible to use sizeof, alignof, and offsetof to compute
 948 offsets for each structure and type in the standard library, saving to
 949 another datafile. Then, compute this in a similar way for new
 950 binaries, and look for differences.
 951 </para>
 952
 953 <para>
 954 Another approach might be to use the -fdump-class-hierarchy flag to
 955 get information. However, currently this approach gives insufficient
 956 data for use in library testing, as class data members, their offsets,
 957 and other detailed data is not displayed with this flag.
 958 (See g++/7470 on how this was used to find bugs.)
 959 </para>
 960
 961 <para>
 962 Perhaps there are other C++ ABI checkers. If so, please notify
 963 us. We'd like to know about them!
 964 </para>
 965
 966   </sect3>
 967   <sect3 id="abi.testing.multi">
 968     <title>Multiple ABI Testing</title>
 969 <para>
 970 A "C" application, dynamically linked to two shared libraries, liba,
 971 libb. The dependent library liba is C++ shared library compiled with
 972 gcc-3.3.x, and uses io, exceptions, locale, etc. The dependent library
 973 libb is a C++ shared library compiled with gcc-3.4.x, and also uses io,
 974 exceptions, locale, etc.
 975 </para>
 976
 977 <para> As above, libone is constructed as follows: </para>
 978 <programlisting>
 979 %$bld/H-x86-gcc-3.4.0/bin/g++ -fPIC -DPIC -c a.cc
 980
 981 %$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
 982
 983 %ln -s libone.so.1.0.0 libone.so
 984
 985 %$bld/H-x86-gcc-3.4.0/bin/g++ -c a.cc
 986
 987 %ar cru libone.a a.o
 988 </programlisting>
 989
 990 <para> And, libtwo is constructed as follows: </para>
 991
 992 <programlisting>
 993 %$bld/H-x86-gcc-3.3.3/bin/g++ -fPIC -DPIC -c b.cc
 994
 995 %$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
 996
 997 %ln -s libtwo.so.1.0.0 libtwo.so
 998
 999 %$bld/H-x86-gcc-3.3.3/bin/g++ -c b.cc
1000
1001 %ar cru libtwo.a b.o
1002 </programlisting>
1003
1004 <para> ...with the resulting libraries looking like </para>
1005
1006 <screen>
1007 <computeroutput>
1008 %ldd libone.so.1.0.0
1009         libstdc++.so.6 =&gt; /usr/lib/libstdc++.so.6 (0x40016000)
1010         libm.so.6 =&gt; /lib/tls/libm.so.6 (0x400fa000)
1011         libgcc_s.so.1 =&gt; /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x4011c000)
1012         libc.so.6 =&gt; /lib/tls/libc.so.6 (0x40125000)
1013         /lib/ld-linux.so.2 =&gt; /lib/ld-linux.so.2 (0x00355000)
1014
1015 %ldd libtwo.so.1.0.0
1016         libstdc++.so.5 =&gt; /usr/lib/libstdc++.so.5 (0x40027000)
1017         libm.so.6 =&gt; /lib/tls/libm.so.6 (0x400e1000)
1018         libgcc_s.so.1 =&gt; /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40103000)
1019         libc.so.6 =&gt; /lib/tls/libc.so.6 (0x4010c000)
1020         /lib/ld-linux.so.2 =&gt; /lib/ld-linux.so.2 (0x00355000)
1021 </computeroutput>
1022 </screen>
1023
1024 <para>
1025   Then, the "C" compiler is used to compile a source file that uses
1026   functions from each library.
1027 </para>
1028 <programlisting>
1029 gcc test.c -g -O2 -L. -lone -ltwo /usr/lib/libstdc++.so.5 /usr/lib/libstdc++.so.6
1030 </programlisting>
1031
1032 <para>
1033   Which gives the expected:
1034 </para>
1035
1036 <screen>
1037 <computeroutput>
1038 %ldd a.out
1039         libstdc++.so.5 =&gt; /usr/lib/libstdc++.so.5 (0x00764000)
1040         libstdc++.so.6 =&gt; /usr/lib/libstdc++.so.6 (0x40015000)
1041         libc.so.6 =&gt; /lib/tls/libc.so.6 (0x0036d000)
1042         libm.so.6 =&gt; /lib/tls/libm.so.6 (0x004a8000)
1043         libgcc_s.so.1 =&gt; /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x400e5000)
1044         /lib/ld-linux.so.2 =&gt; /lib/ld-linux.so.2 (0x00355000)
1045 </computeroutput>
1046 </screen>
1047
1048 <para>
1049   This resulting binary, when executed, will be able to safely use
1050   code from both liba, and the dependent libstdc++.so.6, and libb,
1051   with the dependent libstdc++.so.5.
1052 </para>
1053   </sect3>
1054 </sect2>
1055
1056 <sect2 id="abi.issues">
1057 <title>Outstanding Issues</title>
1058
1059 <para>
1060   Some features in the C++ language make versioning especially
1061   difficult. In particular, compiler generated constructs such as
1062   implicit instantiations for templates, typeinfo information, and
1063   virtual tables all may cause ABI leakage across shared library
1064   boundaries. Because of this, mixing C++ ABIs is not recommended at
1065   this time.
1066 </para>
1067
1068 <para>
1069   For more background on this issue, see these bugzilla entries:
1070 </para>
1071
1072 <para>
1073 <ulink url="http://gcc.gnu.org/PR24660">24660: versioning weak symbols in libstdc++</ulink>
1074 </para>
1075
1076 <para>
1077 <ulink url="http://gcc.gnu.org/PR19664">19664: libstdc++ headers should have pop/push of the visibility around the declarations</ulink>
1078 </para>
1079
1080 </sect2>
1081
1082 <bibliography id="abi.biblio">
1083 <title>Bibliography</title>
1084
1085   <biblioentry>
1086     <biblioid class="uri">
1087       <ulink url="http://abicheck.sourceforge.net/">
1088         <citetitle>
1089           ABIcheck, a vague idea of checking ABI compatibility
1090         </citetitle>
1091       </ulink>
1092     </biblioid>
1093   </biblioentry>
1094
1095   <biblioentry>
1096     <biblioid class="uri">
1097       <ulink url="http://www.codesourcery.com/public/cxx-abi/">
1098         <citetitle>
1099           C++ ABI Reference
1100         </citetitle>
1101       </ulink>
1102     </biblioid>
1103   </biblioentry>
1104
1105   <biblioentry>
1106     <biblioid class="uri">
1107       <ulink url="http://www.intel.com/cd/software/products/asmo-na/eng/284736.htm">
1108         <citetitle>
1109           Intel Compilers for Linux Compatibility with the GNU Compilers
1110         </citetitle>
1111       </ulink>
1112     </biblioid>
1113   </biblioentry>
1114
1115   <biblioentry>
1116     <biblioid class="uri">
1117       <ulink url="http://docs.sun.com/app/docs/doc/817-1984">
1118         <citetitle>
1119           Sun Solaris 2.9 : Linker and Libraries Guide (document 816-1386)
1120         </citetitle>
1121       </ulink>
1122     </biblioid>
1123   </biblioentry>
1124
1125
1126   <biblioentry>
1127     <biblioid class="uri">
1128       <ulink url="http://docs.sun.com/app/docs/doc/819-5266">
1129         <citetitle>
1130           Sun Solaris 2.9 : C++ Migration Guide (document 816-2459)
1131         </citetitle>
1132       </ulink>
1133     </biblioid>
1134   </biblioentry>
1135
1136   <biblioentry>
1137     <biblioid class="uri">
1138       <ulink url="http://people.redhat.com/drepper/dsohowto.pdf">
1139         <citetitle>
1140           How to Write Shared Libraries
1141         </citetitle>
1142       </ulink>
1143     </biblioid>
1144
1145     <author>
1146       <firstname>Ulrich</firstname>
1147       <surname>Drepper</surname>
1148     </author>
1149   </biblioentry>
1150
1151   <biblioentry>
1152     <biblioid class="uri">
1153       <ulink url="http://www.arm.com/miscPDFs/8033.pdf">
1154         <citetitle>
1155           C++ ABI for the ARM Architecture
1156         </citetitle>
1157       </ulink>
1158     </biblioid>
1159   </biblioentry>
1160
1161   <biblioentry>
1162     <biblioid class="uri">
1163       <ulink url="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1976.html">
1164         <citetitle>
1165           Dynamic Shared Objects: Survey and Issues
1166         </citetitle>
1167       </ulink>
1168     </biblioid>
1169     <subtitle>
1170       ISO C++ J16/06-0046
1171     </subtitle>
1172     <author>
1173       <firstname>Benjamin</firstname>
1174       <surname>Kosnik</surname>
1175     </author>
1176   </biblioentry>
1177
1178   <biblioentry>
1179     <biblioid class="uri">
1180       <ulink url="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n2013.html">
1181         <citetitle>
1182           Versioning With Namespaces
1183         </citetitle>
1184       </ulink>
1185     </biblioid>
1186     <subtitle>
1187       ISO C++ J16/06-0083
1188     </subtitle>
1189     <author>
1190       <firstname>Benjamin</firstname>
1191       <surname>Kosnik</surname>
1192     </author>
1193   </biblioentry>
1194
1195   <biblioentry>
1196     <biblioid class="uri">
1197       <ulink url="http://syrcose.ispras.ru/2009/files/SYRCoSE2009-CfP.pdf">
1198         <citetitle>
1199           Binary Compatibility of Shared Libraries Implemented in C++
1200           on GNU/Linux Systems
1201         </citetitle>
1202       </ulink>
1203     </biblioid>
1204     <subtitle>
1205       SYRCoSE 2009
1206     </subtitle>
1207     <author>
1208       <firstname>Pavel</firstname>
1209       <surname>Shved</surname>
1210     </author>
1211     <author>
1212       <firstname>Denis</firstname>
1213       <surname>Silakov</surname>
1214     </author>
1215   </biblioentry>
1216 </bibliography>
1217
1218 </sect1>