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.0: libgcc_s.so.1</li>
 172     </ul>
 173     <p></p>
 174     </li>
 175
 176     <li>Release versioning on the libstdc++.so binary, implemented in the same was as the libgcc_s.so binary, above.
 177
 178     <p>It is versioned as follows:
 179     </p>
 180     <ul>
 181     <li>gcc-3.0.0: libstdc++.so.3.0.0</li>
 182     <li>gcc-3.0.1: libstdc++.so.3.0.1</li>
 183     <li>gcc-3.0.2: libstdc++.so.3.0.2</li>
 184     <li>gcc-3.0.3: libstdc++.so.3.0.2 (Error should be libstdc++.so.3.0.3)</li>
 185     <li>gcc-3.0.4: libstdc++.so.3.0.4</li>
 186     <li>gcc-3.1.0: libstdc++.so.4.0.0</li>
 187     <li>gcc-3.1.1: libstdc++.so.4.0.1</li>
 188     <li>gcc-3.2.0: libstdc++.so.5.0.0</li>
 189     <li>gcc-3.2.1: libstdc++.so.5.0.1</li>
 190     <li>gcc-3.2.2: libstdc++.so.5.0.2</li>
 191     <li>gcc-3.2.3: libstdc++.so.5.0.3 (Not strictly required)</li>
 192     <li>gcc-3.3.0: libstdc++.so.5.0.4</li>
 193     <li>gcc-3.3.1: libstdc++.so.5.0.5</li>
 194     <li>gcc-3.3.2: libstdc++.so.5.0.5</li>
 195     <li>gcc-3.3.3: libstdc++.so.5.0.5</li>
 196     <li>gcc-3.4.0: libstdc++.so.6.0.0</li>
 197     </ul>
 198     <p></p>
 199     </li>
 200
 201     <li>Symbol versioning on the libgcc_s.so binary.
 202     <p>mapfile: gcc/libgcc-std.ver</p>
 203
 204     <p>It is versioned with the following labels and version definitions:</p>
 205     <ul>
 206     <li>gcc-3.0.0: GCC_3.0</li>
 207     <li>gcc-3.0.1: GCC_3.0</li>
 208     <li>gcc-3.0.2: GCC_3.0</li>
 209     <li>gcc-3.0.3: GCC_3.0</li>
 210     <li>gcc-3.0.4: GCC_3.0</li>
 211     <li>gcc-3.1.0: GCC_3.0</li>
 212     <li>gcc-3.1.1: GCC_3.0</li>
 213     <li>gcc-3.2.0: GCC_3.0</li>
 214     <li>gcc-3.2.1: GCC_3.0</li>
 215     <li>gcc-3.2.2: GCC_3.0</li>
 216     <li>gcc-3.2.3: GCC_3.0</li>
 217     <li>gcc-3.3.0: GCC_3.0</li>
 218     <li>gcc-3.3.1: GCC_3.0</li>
 219     <li>gcc-3.3.2: GCC_3.0</li>
 220     <li>gcc-3.3.3: GCC_3.0</li>
 221     <li>gcc-3.4.0: GCC_3.0</li>
 222     </ul>
 223     <p></p>
 224     </li>
 225
 226     <li>Symbol versioning on the libstdc++.so binary.
 227
 228     <p>mapfile: libstdc++-v3/config/linker-map.gnu</p>
 229     <p>It is versioned with the following labels and version
 230    definitions, where the version definition is the maximum for a
 231    particular release. Note, only symbol which are newly introduced
 232    will use the maximum version definition. Thus, for release series
 233    with the same label, but incremented version definitions, the later
 234    release has both versions. (An example of this would be the
 235    gcc-3.2.1 release, which has GLIBCPP_3.2.1 for new symbols and
 236    GLIBCPP_3.2 for symbols that were introduced in the gcc-3.2.0
 237    release.)
 238    </p>
 239     <ul>
 240     <li>gcc-3.0.0: (Error, not versioned)</li>
 241     <li>gcc-3.0.1: (Error, not versioned)</li>
 242     <li>gcc-3.0.2: (Error, not versioned)</li>
 243     <li>gcc-3.0.3: (Error, not versioned)</li>
 244     <li>gcc-3.0.4: (Error, not versioned)</li>
 245     <li>gcc-3.1.0: GLIBCPP_3.1, CXXABI_1</li>
 246     <li>gcc-3.1.1: GLIBCPP_3.1, CXXABI_1</li>
 247     <li>gcc-3.2.0: GLIBCPP_3.2, CXXABI_1.2</li>
 248     <li>gcc-3.2.1: GLIBCPP_3.2.1, CXXABI_1.2</li>
 249     <li>gcc-3.2.2: GLIBCPP_3.2.2, CXXABI_1.2</li>
 250     <li>gcc-3.2.3: GLIBCPP_3.2.2, CXXABI_1.2</li>
 251     <li>gcc-3.3.0: GLIBCPP_3.2.2, CXXABI_1.2.1</li>
 252     <li>gcc-3.3.1: GLIBCPP_3.2.3, CXXABI_1.2.1</li>
 253     <li>gcc-3.3.2: GLIBCPP_3.2.3, CXXABI_1.2.1</li>
 254     <li>gcc-3.3.3: GLIBCPP_3.2.3, CXXABI_1.2.1</li>
 255     <li>gcc-3.4.0: GLIBCXX_3.4, CXXABI_1.3</li>
 256     </ul>
 257     <p></p>
 258     </li>
 259
 260     <li>
 261     <p>Incremental bumping of a compiler pre-defined macro,
 262     __GXX_ABI_VERSION. This macro is defined as the version of the
 263     compiler v3 ABI, with g++ 3.0.x being version 100. This macro will
 264     be automatically defined whenever g++ is used (the curious can
 265     test this by invoking g++ with the '-v' flag.)
 266     </p>
 267
 268     <p>
 269     This macro was defined in the file "lang-specs.h" in the gcc/cp directory.
 270     Later versions defined it in "c-common.c" in the gcc directory, and from
 271     G++ 3.4 it is defined in c-cppbuiltin.c and its value determined by the
 272     '-fabi-version' command line option.
 273     </p>
 274
 275     <p>
 276     It is versioned as follows, where 'n' is given by '-fabi-version=n':
 277     </p>
 278     <ul>
 279     <li>gcc-3.0.x: 100</li>
 280     <li>gcc-3.1.x: 100 (Error, should be 101)</li>
 281     <li>gcc-3.2.x: 102</li>
 282     <li>gcc-3.3.x: 102</li>
 283     <li>gcc-3.4.x: 102 (when n=1)</li>
 284     <li>gcc-3.4.x: 1000+n (when n&gt;1)</li>
 285     <li>gcc-3.4.x: 999999 (when n=0)</li>
 286     </ul>
 287     <p></p>
 288     </li>
 289
 290     <li>
 291     <p>Changes to the default compiler option for
 292     <code>-fabi-version</code>.
 293     </p>
 294    <p>
 295     It is versioned as follows:
 296     </p>
 297     <ul>
 298     <li>gcc-3.0.x: (Error, not versioned) </li>
 299     <li>gcc-3.1.x: (Error, not versioned) </li>
 300     <li>gcc-3.2.x: <code>-fabi-version=1</code></li>
 301     <li>gcc-3.3.x: <code>-fabi-version=1</code></li>
 302     <li>gcc-3.4.x: <code>-fabi-version=2</code></li>
 303     </ul>
 304     <p></p>
 305     </li>
 306
 307    <li>
 308     <p>Incremental bumping of a library pre-defined macro. For releases
 309     before 3.4.0, the macro is __GLIBCPP__. For later releases, it's
 310     __GLIBCXX__. (The libstdc++ project generously changed from CPP to
 311     CXX throughout its source to allow the "C" pre-processor the CPP
 312     macro namespace.) These macros are defined as the date the library
 313     was released, in compressed ISO date format, as an unsigned long.
 314     </p>
 315
 316     <p>
 317     In addition, the pre-defined macro is defined in the file
 318     "c++config" in the "libstdc++-v3/include/bits" directory and is
 319     changed every night by an automated script.
 320     </p>
 321     <p>
 322     It is versioned as follows:
 323     </p>
 324     <ul>
 325     <li>gcc-3.0.0: 20010615</li>
 326     <li>gcc-3.0.1: 20010819</li>
 327     <li>gcc-3.0.2: 20011023</li>
 328     <li>gcc-3.0.3: 20011220</li>
 329     <li>gcc-3.0.4: 20020220</li>
 330     <li>gcc-3.1.0: 20020514</li>
 331     <li>gcc-3.1.1: 20020725</li>
 332     <li>gcc-3.2.0: 20020814</li>
 333     <li>gcc-3.2.1: 20021119</li>
 334     <li>gcc-3.2.2: 20030205</li>
 335     <li>gcc-3.2.3: 20030422</li>
 336     <li>gcc-3.3.0: 20030513</li>
 337     <li>gcc-3.3.1: 20030804</li>
 338     <li>gcc-3.3.2: 20031016</li>
 339     <li>gcc-3.3.3: 20040214</li>
 340     <li>gcc-3.4.0: 20040419</li>
 341     </ul>
 342     <p></p>
 343     </li>
 344
 345
 346     <li>
 347     <p>
 348     Incremental bumping of a library pre-defined macro,
 349     _GLIBCPP_VERSION. This macro is defined as the released version of
 350     the library, as a string literal. This is only implemented in
 351     gcc-3.1.0 releases and higher, and is deprecated in 3.4 (where it
 352     is called _GLIBCXX_VERSION).
 353     </p>
 354
 355     <p>
 356     This macro is defined in the file "c++config" in the
 357     "libstdc++-v3/include/bits" directory and is generated
 358     automatically by autoconf as part of the configure-time generation
 359     of config.h.
 360     </p>
 361
 362     <p>
 363     It is versioned as follows:
 364     </p>
 365     <ul>
 366     <li>gcc-3.0.0: "3.0.0"</li>
 367     <li>gcc-3.0.1: "3.0.0" (Error, should be "3.0.1")</li>
 368     <li>gcc-3.0.2: "3.0.0" (Error, should be "3.0.2")</li>
 369     <li>gcc-3.0.3: "3.0.0" (Error, should be "3.0.3")</li>
 370     <li>gcc-3.0.4: "3.0.0" (Error, should be "3.0.4")</li>
 371     <li>gcc-3.1.0: "3.1.0"</li>
 372     <li>gcc-3.1.1: "3.1.1"</li>
 373     <li>gcc-3.2.0: "3.2"</li>
 374     <li>gcc-3.2.1: "3.2.1"</li>
 375     <li>gcc-3.2.2: "3.2.2"</li>
 376     <li>gcc-3.2.3: "3.2.3"</li>
 377     <li>gcc-3.3.0: "3.3"</li>
 378     <li>gcc-3.3.1: "3.3.1"</li>
 379     <li>gcc-3.3.2: "3.3.2"</li>
 380     <li>gcc-3.3.3: "3.3.3"</li>
 381     <li>gcc-3.4.0: "version-unused"</li>
 382     </ul>
 383     <p></p>
 384     </li>
 385
 386     <li>
 387     <p>
 388     Matching each specific C++ compiler release to a specific set of
 389     C++ include files. This is only implemented in gcc-3.1.1 releases
 390     and higher.
 391     </p>
 392     <p>
 393     All C++ includes are installed in include/c++, then nest in a
 394     directory hierarchy corresponding to the C++ compiler's released
 395     version. This version corresponds to the variable "gcc_version" in
 396     "libstdc++-v3/acinclude.m4," and more details can be found in that
 397     file's macro GLIBCXX_CONFIGURE (GLIBCPP_CONFIGURE before gcc-3.4.0).
 398     </p>
 399     <p>
 400     C++ includes are versioned as follows:
 401     </p>
 402     <ul>
 403     <li>gcc-3.0.0: include/g++-v3</li>
 404     <li>gcc-3.0.1: include/g++-v3</li>
 405     <li>gcc-3.0.2: include/g++-v3</li>
 406     <li>gcc-3.0.3: include/g++-v3</li>
 407     <li>gcc-3.0.4: include/g++-v3</li>
 408     <li>gcc-3.1.0: include/g++-v3</li>
 409     <li>gcc-3.1.1: include/c++/3.1.1</li>
 410     <li>gcc-3.2.0: include/c++/3.2</li>
 411     <li>gcc-3.2.1: include/c++/3.2.1</li>
 412     <li>gcc-3.2.2: include/c++/3.2.2</li>
 413     <li>gcc-3.2.3: include/c++/3.2.3</li>
 414     <li>gcc-3.3.0: include/c++/3.3</li>
 415     <li>gcc-3.3.1: include/c++/3.3.1</li>
 416     <li>gcc-3.3.2: include/c++/3.3.2</li>
 417     <li>gcc-3.3.3: include/c++/3.3.3</li>
 418     <li>gcc-3.4.0: include/c++/3.4.0</li>
 419     </ul>
 420     <p></p>
 421     </li>
 422   </ul>
 423 <p>
 424   Taken together, these techniques can accurately specify interface
 425   and implementation changes in the GNU C++ tools themselves. Used
 426   properly, they allow both the GNU C++ tools implementation, and
 427   programs using them, an evolving yet controlled development that
 428   maintains backward compatibility.
 429 </p>
 430
 431
 432
 433 <h5 class="left">
 434   <a name="requirements"> Minimum requirements for a versioned ABI </a>
 435 </h5>
 436 <p>
 437   Minimum environment that supports a versioned ABI: A supported
 438   dynamic linker, a GNU linker of sufficient vintage to understand
 439   demangled C++ name globbing (ld), a shared executable compiled with
 440   g++, and shared libraries (libgcc_s, libstdc++-v3) compiled by a
 441   compiler (g++) with a compatible ABI. Phew.
 442 </p>
 443
 444 <p>
 445   On top of all that, an additional constraint: libstdc++ did not
 446   attempt to version symbols (or age gracefully, really) until version
 447   3.1.0.
 448 </p>
 449
 450 <p>
 451   Most modern Linux and BSD versions, particularly ones using
 452   gcc-3.1.x tools and more recent vintages, will meet the requirements above.
 453 </p>
 454
 455
 456 <h5 class="left">
 457   <a name="config"> What configure options impact symbol versioning? </a>
 458 </h5>
 459 <p>
 460   It turns out that most of the configure options that change default
 461   behavior will impact the mangled names of exported symbols, and thus
 462   impact versioning and compatibility.
 463 </p>
 464
 465 <p>
 466   For more information on configure options, including ABI impacts, see:
 467   http://gcc.gnu.org/onlinedocs/libstdc++/configopts.html
 468 </p>
 469
 470 <p>
 471   There is one flag that explicitly deals with symbol versioning:
 472   --enable-symvers.
 473 </p>
 474
 475 <p>
 476   In particular, libstdc++-v3/acinclude.m4 has a macro called
 477   GLIBCXX_ENABLE_SYMVERS that defaults to yes (or the argument passed
 478   in via --enable-symvers=foo). At that point, the macro attempts to
 479   make sure that all the requirement for symbol versioning are in
 480   place. For more information, please consult acinclude.m4.
 481 </p>
 482
 483
 484 <h5 class="left">
 485   <a name="active"> How to tell if symbol versioning is, indeed, active? </a>
 486 </h5>
 487 <p>
 488   When the GNU C++ library is being built with symbol versioning on,
 489   you should see the following at configure time for libstdc++-v3:
 490 </p>
 491
 492
 493 <code>  checking versioning on shared library symbols... gnu</code>
 494
 495 <p>
 496   If you don't see this line in the configure output, or if this line
 497   appears but the last word is 'no', then you are out of luck.
 498 </p>
 499
 500 <p>
 501   If the compiler is pre-installed, a quick way to test is to compile
 502   the following (or any) simple C++ file and link it to the shared
 503   libstdc++ library:
 504 </p>
 505
 506 <pre>
 507 #include &lt;iostream&gt;
 508
 509 int main()
 510 { std::cout &lt;&lt; "hello" &lt;&lt; std::endl; return 0; }
 511
 512 %g++ hello.cc -o hello.out
 513
 514 %ldd hello.out
 515         libstdc++.so.5 =&gt; /usr/lib/libstdc++.so.5 (0x00764000)
 516         libm.so.6 =&gt; /lib/tls/libm.so.6 (0x004a8000)
 517         libgcc_s.so.1 =&gt; /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40016000)
 518         libc.so.6 =&gt; /lib/tls/libc.so.6 (0x0036d000)
 519         /lib/ld-linux.so.2 =&gt; /lib/ld-linux.so.2 (0x00355000)
 520
 521 %nm hello.out
 522 </pre>
 523
 524 <p>
 525 If you see symbols in the resulting output with "GLIBCXX_3" as part
 526 of the name, then the executable is versioned. Here's an example:
 527 </p>
 528
 529    <code>      U _ZNSt8ios_base4InitC1Ev@@GLIBCXX_3.4 </code>
 530
 531 <h3 class="left">
 532   <a name="ABI_allowed">Library allowed ABI changes</a>
 533 </h3>
 534 <p>
 535 The following will cause the library minor version number to
 536 increase, say from "libstdc++.so.3.0.4" to "libstdc++.so.3.0.5".
 537 </p>
 538 <ul>
 539  <li>adding an exported global or static data member</li>
 540  <li>adding an exported function, static or non-virtual member function</li>
 541  <li>adding an exported symbol or symbols by additional instantiations</li>
 542 </ul>
 543 <p>
 544 </p>
 545 <p>
 546 Other allowed changes are possible.
 547 </p>
 548
 549
 550 <h3 class="left">
 551   <a name="ABI_disallowed">Library disallowed ABI changes</a>
 552 </h3>
 553
 554 <p>
 555 The following non-exhaustive list will cause the library major version
 556 number to increase, say from "libstdc++.so.3.0.4" to
 557 "libstdc++.so.4.0.0".
 558 </p>
 559 <ul>
 560  <li>changes in the gcc/g++ compiler ABI</li>
 561 <li>changing size of an exported symbol</li>
 562 <li>changing alignment of an exported symbol</li>
 563 <li>changing the layout of an exported symbol</li>
 564 <li>changing mangling on an exported symbol</li>
 565 <li>deleting an exported symbol</li>
 566 <li>changing the inheritance properties of a type by adding or removing
 567     base classes</li>
 568 <li>
 569   changing the size, alignment, or layout of types
 570   specified in the C++ standard. These may not necessarily be
 571   instantiated or otherwise exported in the library binary, and
 572   include all the required locale facets, as well as things like
 573   std::basic_streambuf, et al.
 574 </li>
 575 </ul>
 576
 577 <h3 class="left">
 578   <a name="implementation">Library implementation strategy</a>
 579 </h3>
 580
 581 <ul>
 582  <li>Separation of interface and implementation
 583 <p>This is accomplished by two techniques that separate the API from
 584 the ABI: forcing undefined references to link against a library binary
 585 for definitions.
 586 </p>
 587
 588  <dl>
 589   <dt>Include files have declarations, source files have defines</dt>
 590
 591    <dd> For non-templatized types, such as much of <code>class
 592    locale</code>, the appropriate standard C++ include, say
 593    <code>locale</code>, can contain full declarations, while various
 594    source files (say <code> locale.cc, locale_init.cc,
 595    localename.cc</code>) contain definitions.</dd>
 596
 597   <dt>Extern template on required types</dt>
 598
 599    <dd>For parts of the standard that have an explicit list of required
 600    instantiations, the GNU extension syntax <code> extern template
 601    </code> can be used to control where template definitions
 602    reside. By marking required instantiations as <code> extern
 603    template </code> in include files, and providing explicit
 604    instantiations in the appropriate instantiation files, non-inlined
 605    template functions can be versioned. This technique is mostly used
 606    on parts of the standard that require <code> char</code> and <code>
 607    wchar_t</code> instantiations, and includes <code>
 608    basic_string</code>, the locale facets, and the types in <code>
 609    iostreams</code>.</dd>
 610
 611  </dl>
 612  <p> In addition, these techniques have the additional benefit that
 613  they reduce binary size, which can increase runtime performance.
 614  </p>
 615  </li>
 616
 617  <li>Namespaces linking symbol definitions to export mapfiles
 618
 619 <p>All symbols in the shared library binary are processed by a linker
 620 script at build time that either allows or disallows external
 621 linkage. Because of this, some symbols, regardless of normal C/C++
 622 linkage, are not visible. Symbols that are internal have several
 623 appealing characteristics: by not exporting the symbols, there are no
 624 relocations when the shared library is started and thus this makes for
 625 faster runtime loading performance by the underlying dynamic loading
 626 mechanism. In addition, they have the possibility of changing without
 627 impacting ABI compatibility.
 628 </p>
 629
 630 <p>The following namespaces are transformed by the mapfile:</p>
 631
 632 <dl>
 633 <dt><code>namespace std</code></dt>
 634 <dd> Defaults to exporting all symbols in label
 635 <code>GLIBCXX</code> that do not begin with an underscore, ie
 636 <code>__test_func</code> would not be exported by default. Select
 637 exceptional symbols are allowed to be visible.</dd>
 638
 639 <dt><code>namespace __gnu_cxx</code></dt>
 640 <dd> Defaults to not exporting any symbols in label
 641 <code>GLIBCXX</code>, select items are allowed to be visible.</dd>
 642
 643 <dt><code>namespace __gnu_internal</code></dt>
 644 <dd> Defaults to not exported, no items are allowed to be visible.</dd>
 645
 646 <dt><code>namespace __cxxabiv1</code>, aliased to <code> namespace abi</code></dt>
 647 <dd> Defaults to not exporting any symbols in label
 648 <code>CXXABI</code>, select items are allowed to be visible.</dd>
 649 </dl>
 650 <p>
 651 </p>
 652 </li>
 653
 654  <li>Freezing the API
 655  <p>Disallowed changes, as above, are not made on a stable release
 656 branch. Enforcement tends to be less strict with GNU extensions that
 657 standard includes.</p>
 658 </li>
 659 </ul>
 660
 661 <h3 class="left">
 662   <a name="ABI_testing">Testing ABI changes</a>
 663 </h3>
 664
 665 <p>
 666 Testing for GNU C++ ABI changes is composed of two distinct areas:
 667 testing the C++ compiler (g++) for compiler changes, and testing the
 668 C++ library (libstdc++) for library changes.
 669 </p>
 670
 671 <p>
 672 Testing the C++ compiler ABI can be done various ways.
 673 </p>
 674
 675 <p>
 676 One.
 677 Intel ABI checker. More information can be obtained
 678 <a href="http://developer.intel.com/software/products/opensource/">here.</a>
 679 </p>
 680
 681 <p>
 682 Two.
 683 The second is yet unreleased, but has been announced on the gcc
 684 mailing list. It is yet unspecified if these tools will be freely
 685 available, and able to be included in a GNU project. Please contact
 686 Mark Mitchell (mark@codesourcery.com) for more details, and current
 687 status.
 688 </p>
 689
 690 <p>
 691 Three.
 692 Involves using the vlad.consistency test framework. This has also been
 693 discussed on the gcc mailing lists.
 694 </p>
 695
 696 <p>
 697 Testing the C++ library ABI can also be done various ways.
 698 </p>
 699
 700 <p>
 701 One.
 702 (Brendan Kehoe, Jeff Law suggestion to run 'make check-c++' two ways,
 703 one with a new compiler and an old library, and the other with an old
 704 compiler and a new library, and look for testsuite regressions)
 705 </p>
 706
 707 <p>
 708 Details on how to set this kind of test up can be found here:
 709 http://gcc.gnu.org/ml/gcc/2002-08/msg00142.html
 710 </p>
 711
 712 <p>
 713 Two.
 714 Use the 'make check-abi' rule in the libstdc++-v3 Makefile.
 715 </p>
 716
 717 <p>
 718 This is a proactive check the library ABI. Currently, exported symbol
 719 names that are either weak or defined are checked against a last known
 720 good baseline. Currently, this baseline is keyed off of 3.2.0
 721 binaries, as this was the last time the .so number was incremented. In
 722 addition, all exported names are demangled, and the exported objects
 723 are checked to make sure they are the same size as the same object in
 724 the baseline.
 725 </p>
 726
 727 <p>
 728 This dataset is insufficient, yet a start. Also needed is a
 729 comprehensive check for all user-visible types part of the standard
 730 library for sizeof() and alignof() changes.
 731 </p>
 732
 733 <p>
 734 Verifying compatible layouts of objects is not even attempted.  It
 735 should be possible to use sizeof, alignof, and offsetof to compute
 736 offsets for each structure and type in the standard library, saving to
 737 another datafile. Then, compute this in a similar way for new
 738 binaries, and look for differences.
 739 </p>
 740
 741 <p>
 742 Another approach might be to use the -fdump-class-hierarchy flag to
 743 get information. However, currently this approach gives insufficient
 744 data for use in library testing, as class data members, their offsets,
 745 and other detailed data is not displayed with this flag.
 746 (See g++/7470 on how this was used to find bugs.)
 747 </p>
 748
 749 <p>
 750 Perhaps there are other C++ ABI checkers. If so, please notify
 751 us. We'd like to know about them!
 752 </p>
 753
 754 <h3 class="left">
 755   <a name="ABI_multi_testing">Testing Multi-ABI binaries</a>
 756 </h3>
 757
 758 <p>
 759 A "C" application, dynamically linked to two shared libraries, liba,
 760 libb. The dependent library liba is C++ shared library compiled with
 761 gcc-3.3.x, and uses io, exceptions, locale, etc. The dependent library
 762 libb is a C++ shared library compiled with gcc-3.4.x, and also uses io,
 763 exceptions, locale, etc.
 764 </p>
 765
 766 <p> As above, libone is constructed as follows: </p>
 767 <pre>
 768 %$bld/H-x86-gcc-3.4.0/bin/g++ -fPIC -DPIC -c a.cc
 769
 770 %$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
 771
 772 %ln -s libone.so.1.0.0 libone.so
 773
 774 %$bld/H-x86-gcc-3.4.0/bin/g++ -c a.cc
 775
 776 %ar cru libone.a a.o
 777 </pre>
 778
 779 <p> And, libtwo is constructed as follows: </p>
 780
 781 <pre>
 782 %$bld/H-x86-gcc-3.3.3/bin/g++ -fPIC -DPIC -c b.cc
 783
 784 %$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
 785
 786 %ln -s libtwo.so.1.0.0 libtwo.so
 787
 788 %$bld/H-x86-gcc-3.3.3/bin/g++ -c b.cc
 789
 790 %ar cru libtwo.a b.o
 791 </pre>
 792
 793 <p> ...with the resulting libraries looking like </p>
 794 <pre>
 795 %ldd libone.so.1.0.0
 796         libstdc++.so.6 =&gt; /usr/lib/libstdc++.so.6 (0x40016000)
 797         libm.so.6 =&gt; /lib/tls/libm.so.6 (0x400fa000)
 798         libgcc_s.so.1 =&gt; /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x4011c000)
 799         libc.so.6 =&gt; /lib/tls/libc.so.6 (0x40125000)
 800         /lib/ld-linux.so.2 =&gt; /lib/ld-linux.so.2 (0x00355000)
 801
 802 %ldd libtwo.so.1.0.0
 803         libstdc++.so.5 =&gt; /usr/lib/libstdc++.so.5 (0x40027000)
 804         libm.so.6 =&gt; /lib/tls/libm.so.6 (0x400e1000)
 805         libgcc_s.so.1 =&gt; /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40103000)
 806         libc.so.6 =&gt; /lib/tls/libc.so.6 (0x4010c000)
 807         /lib/ld-linux.so.2 =&gt; /lib/ld-linux.so.2 (0x00355000)
 808
 809 </pre>
 810
 811 <p> Then, the "C" compiler is used to compile a source file that uses
 812 functions from each library.</p>
 813 <pre>
 814 gcc test.c -g -O2 -L. -lone -ltwo /usr/lib/libstdc++.so.5 /usr/lib/libstdc++.so.6
 815 </pre>
 816
 817 <p>
 818 Which gives the expected:
 819 </p>
 820 <pre>
 821 %ldd a.out
 822         libstdc++.so.5 =&gt; /usr/lib/libstdc++.so.5 (0x00764000)
 823         libstdc++.so.6 =&gt; /usr/lib/libstdc++.so.6 (0x40015000)
 824         libc.so.6 =&gt; /lib/tls/libc.so.6 (0x0036d000)
 825         libm.so.6 =&gt; /lib/tls/libm.so.6 (0x004a8000)
 826         libgcc_s.so.1 =&gt; /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x400e5000)
 827         /lib/ld-linux.so.2 =&gt; /lib/ld-linux.so.2 (0x00355000)
 828 </pre>
 829
 830 <p>
 831 This resulting binary, when executed, will be able to safely use code
 832 from both liba, and the dependent libstdc++.so.6, and libb, with the
 833 dependent libstdc++.so.5.
 834 </p>
 835
 836 <h3 class="left">
 837   <a name="references">Bibliography / Further Reading</a>
 838 </h3>
 839
 840 <p>
 841 ABIcheck, a vague idea of checking ABI compatibility
 842 <br />
 843 <a href="http://abicheck.sourceforge.net/">http://abicheck.sourceforge.net/</a>
 844 </p>
 845
 846 <p>
 847 C++ ABI reference
 848 <br />
 849 <a href="http://www.codesourcery.com/cxx-abi/">http://www.codesourcery.com/cxx-abi/</a>
 850 </p>
 851
 852 <p>
 853 Intel ABI documentation
 854 <br />
 855 "Intel® Compilers for Linux* -Compatibility with the GNU Compilers"
 856 <br />
 857 (included in icc 6.0)
 858 </p>
 859
 860 <p>
 861 Sun Solaris 2.9 docs
 862 <br />
 863 Linker and Libraries Guide (document 816-1386)
 864 <br />
 865 C++ Migration Guide (document 816-2459)
 866 <br />
 867 <a href="http://docs.sun.com/db/prod/solaris.9">http://docs.sun.com/db/prod/solaris.9</a>
 868 <br />
 869 <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>
 870 </p>
 871
 872 <p>
 873 Ulrich Drepper, "ELF Symbol Versioning"
 874 <br />
 875 <a href="http://people.redhat.com/drepper/symbol-versioning">http://people.redhat.com/drepper/symbol-versioning</a>
 876 </p>
 877
 878 </body>
 879 </html>
 880