libstdc++-v3/docs/html/abi.html

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