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