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