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

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