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

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