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