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