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

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