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

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