1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ABI Policy and Guidelines</title><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><meta name="keywords" content="C++, ABI, version, dynamic, shared, compatibility" /><meta name="keywords" content="ISO C++, library" /><meta name="keywords" content="ISO C++, runtime, library" /><link rel="home" href="../index.html" title="The GNU C++ Library" /><link rel="up" href="appendix_porting.html" title="Appendix��B.�� Porting and Maintenance" /><link rel="prev" href="test.html" title="Testing" /><link rel="next" href="api.html" title="API Evolution and Deprecation History" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">ABI Policy and Guidelines</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="test.html">Prev</a>��</td><th width="60%" align="center">Appendix��B.�� 3 Porting and Maintenance 4 5</th><td width="20%" align="right">��<a accesskey="n" href="api.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="appendix.porting.abi"></a>ABI Policy and Guidelines</h2></div></div></div><p> 6</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="abi.cxx_interface"></a>The C++ Interface</h3></div></div></div><p> 7 C++ applications often depend on specific language support 8 routines, say for throwing exceptions, or catching exceptions, and 9 perhaps also depend on features in the C++ Standard Library. 10</p><p> 11 The C++ Standard Library has many include files, types defined in 12 those include files, specific named functions, and other 13 behavior. The text of these behaviors, as written in source include 14 files, is called the Application Programing Interface, or API. 15</p><p> 16 Furthermore, C++ source that is compiled into object files is 17 transformed by the compiler: it arranges objects with specific 18 alignment and in a particular layout, mangling names according to a 19 well-defined algorithm, has specific arrangements for the support of 20 virtual functions, etc. These details are defined as the compiler 21 Application Binary Interface, or ABI. From GCC version 3 onwards the 22 GNU C++ compiler uses an industry-standard C++ ABI, the 23 <a class="link" href="abi.html#biblio.cxxabi" title="Itanium C++ ABI">Itanium C++ ABI</a>. 24</p><p> 25 The GNU C++ compiler, g++, has a compiler command line option to 26 switch between various different C++ ABIs. This explicit version 27 switch is the flag <code class="code">-fabi-version</code>. In addition, some 28 g++ command line options may change the ABI as a side-effect of 29 use. Such flags include <code class="code">-fpack-struct</code> and 30 <code class="code">-fno-exceptions</code>, but include others: see the complete 31 list in the GCC manual under the heading <a class="link" href="http://gcc.gnu.org/onlinedocs/gcc/Code-Gen-Options.html#Code%20Gen%20Options" target="_top">Options 32 for Code Generation Conventions</a>. 33</p><p> 34 The configure options used when building a specific libstdc++ 35 version may also impact the resulting library ABI. The available 36 configure options, and their impact on the library ABI, are 37 documented 38<a class="link" href="configure.html" title="Configure">here</a>. 39</p><p> Putting all of these ideas together results in the C++ Standard 40Library ABI, which is the compilation of a given library API by a 41given compiler ABI. In a nutshell: 42</p><p> 43 <span class="quote">���<span class="quote"> 44 library API + compiler ABI = library ABI 45 </span>���</span> 46</p><p> 47 The library ABI is mostly of interest for end-users who have 48 unresolved symbols and are linking dynamically to the C++ Standard 49 library, and who thus must be careful to compile their application 50 with a compiler that is compatible with the available C++ Standard 51 library binary. In this case, compatible is defined with the equation 52 above: given an application compiled with a given compiler ABI and 53 library API, it will work correctly with a Standard C++ Library 54 created with the same constraints. 55</p><p> 56 To use a specific version of the C++ ABI, one must use a 57 corresponding GNU C++ toolchain (i.e., g++ and libstdc++) that 58 implements the C++ ABI in question. 59</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="abi.versioning"></a>Versioning</h3></div></div></div><p> The C++ interface has evolved throughout the history of the GNU 60C++ toolchain. With each release, various details have been changed so 61as to give distinct versions to the C++ interface. 62</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="abi.versioning.goals"></a>Goals</h4></div></div></div><p>Extending existing, stable ABIs. Versioning gives subsequent 63releases of library binaries the ability to add new symbols and add 64functionality, all the while retaining compatibility with the previous 65releases in the series. Thus, program binaries linked with the initial 66release of a library binary will still run correctly if the library 67binary is replaced by carefully-managed subsequent library 68binaries. This is called forward compatibility. 69</p><p> 70The reverse (backwards compatibility) is not true. It is not possible 71to take program binaries linked with the latest version of a library 72binary in a release series (with additional symbols added), substitute 73in the initial release of the library binary, and remain link 74compatible. 75</p><p>Allows multiple, incompatible ABIs to coexist at the same time. 76</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="abi.versioning.history"></a>History</h4></div></div></div><p> 77 How can this complexity be managed? What does C++ versioning mean? 78 Because library and compiler changes often make binaries compiled 79 with one version of the GNU tools incompatible with binaries 80 compiled with other (either newer or older) versions of the same GNU 81 tools, specific techniques are used to make managing this complexity 82 easier. 83</p><p> 84 The following techniques are used: 85</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Release versioning on the libgcc_s.so binary. </p><p>This is implemented via file names and the ELF 86 <code class="constant">DT_SONAME</code> mechanism (at least on ELF 87 systems). It is versioned as follows: 88 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>GCC 3.x: libgcc_s.so.1</p></li><li class="listitem"><p>GCC 4.x: libgcc_s.so.1</p></li></ul></div><p>For m68k-linux the versions differ as follows: </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>GCC 3.4, GCC 4.x: libgcc_s.so.1 89 when configuring <code class="code">--with-sjlj-exceptions</code>, or 90 libgcc_s.so.2 </p></li></ul></div><p>For hppa-linux the versions differ as follows: </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>GCC 3.4, GCC 4.[0-1]: either libgcc_s.so.1 91 when configuring <code class="code">--with-sjlj-exceptions</code>, or 92 libgcc_s.so.2 </p></li><li class="listitem"><p>GCC 4.[2-7]: either libgcc_s.so.3 when configuring 93 <code class="code">--with-sjlj-exceptions</code>) or libgcc_s.so.4 94 </p></li></ul></div></li><li class="listitem"><p>Symbol versioning on the libgcc_s.so binary.</p><p>It is versioned with the following labels and version 95 definitions, where the version definition is the maximum for a 96 particular release. Labels are cumulative. If a particular release 97 is not listed, it has the same version labels as the preceding 98 release.</p><p>This corresponds to the mapfile: gcc/libgcc-std.ver</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>GCC 3.0.0: GCC_3.0</p></li><li class="listitem"><p>GCC 3.3.0: GCC_3.3</p></li><li class="listitem"><p>GCC 3.3.1: GCC_3.3.1</p></li><li class="listitem"><p>GCC 3.3.2: GCC_3.3.2</p></li><li class="listitem"><p>GCC 3.3.4: GCC_3.3.4</p></li><li class="listitem"><p>GCC 3.4.0: GCC_3.4</p></li><li class="listitem"><p>GCC 3.4.2: GCC_3.4.2</p></li><li class="listitem"><p>GCC 3.4.4: GCC_3.4.4</p></li><li class="listitem"><p>GCC 4.0.0: GCC_4.0.0</p></li><li class="listitem"><p>GCC 4.1.0: GCC_4.1.0</p></li><li class="listitem"><p>GCC 4.2.0: GCC_4.2.0</p></li><li class="listitem"><p>GCC 4.3.0: GCC_4.3.0</p></li><li class="listitem"><p>GCC 4.4.0: GCC_4.4.0</p></li><li class="listitem"><p>GCC 4.5.0: GCC_4.5.0</p></li><li class="listitem"><p>GCC 4.6.0: GCC_4.6.0</p></li><li class="listitem"><p>GCC 4.7.0: GCC_4.7.0</p></li><li class="listitem"><p>GCC 4.8.0: GCC_4.8.0</p></li></ul></div></li><li class="listitem"><p> 99 Release versioning on the libstdc++.so binary, implemented in 100 the same way as the libgcc_s.so binary above. Listed is the 101 filename: <code class="constant">DT_SONAME</code> can be deduced from 102 the filename by removing the last two period-delimited numbers. For 103 example, filename <code class="filename">libstdc++.so.5.0.4</code> 104 corresponds to a <code class="constant">DT_SONAME</code> of 105 <code class="constant">libstdc++.so.5</code>. Binaries with equivalent 106 <code class="constant">DT_SONAME</code>s are forward-compatibile: in 107 the table below, releases incompatible with the previous 108 one are explicitly noted. 109 If a particular release is not listed, its libstdc++.so binary 110 has the same filename and <code class="constant">DT_SONAME</code> as the 111 preceding release. 112 </p><p>It is versioned as follows: 113 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>GCC 3.0.0: libstdc++.so.3.0.0</p></li><li class="listitem"><p>GCC 3.0.1: libstdc++.so.3.0.1</p></li><li class="listitem"><p>GCC 3.0.2: libstdc++.so.3.0.2</p></li><li class="listitem"><p>GCC 3.0.3: libstdc++.so.3.0.2 (See Note 1)</p></li><li class="listitem"><p>GCC 3.0.4: libstdc++.so.3.0.4</p></li><li class="listitem"><p>GCC 3.1.0: libstdc++.so.4.0.0 <span class="emphasis"><em>(Incompatible with previous)</em></span></p></li><li class="listitem"><p>GCC 3.1.1: libstdc++.so.4.0.1</p></li><li class="listitem"><p>GCC 3.2.0: libstdc++.so.5.0.0 <span class="emphasis"><em>(Incompatible with previous)</em></span></p></li><li class="listitem"><p>GCC 3.2.1: libstdc++.so.5.0.1</p></li><li class="listitem"><p>GCC 3.2.2: libstdc++.so.5.0.2</p></li><li class="listitem"><p>GCC 3.2.3: libstdc++.so.5.0.3 (See Note 2)</p></li><li class="listitem"><p>GCC 3.3.0: libstdc++.so.5.0.4</p></li><li class="listitem"><p>GCC 3.3.1: libstdc++.so.5.0.5</p></li><li class="listitem"><p>GCC 3.4.0: libstdc++.so.6.0.0 <span class="emphasis"><em>(Incompatible with previous)</em></span></p></li><li class="listitem"><p>GCC 3.4.1: libstdc++.so.6.0.1</p></li><li class="listitem"><p>GCC 3.4.2: libstdc++.so.6.0.2</p></li><li class="listitem"><p>GCC 3.4.3: libstdc++.so.6.0.3</p></li><li class="listitem"><p>GCC 4.0.0: libstdc++.so.6.0.4</p></li><li class="listitem"><p>GCC 4.0.1: libstdc++.so.6.0.5</p></li><li class="listitem"><p>GCC 4.0.2: libstdc++.so.6.0.6</p></li><li class="listitem"><p>GCC 4.0.3: libstdc++.so.6.0.7</p></li><li class="listitem"><p>GCC 4.1.0: libstdc++.so.6.0.7</p></li><li class="listitem"><p>GCC 4.1.1: libstdc++.so.6.0.8</p></li><li class="listitem"><p>GCC 4.2.0: libstdc++.so.6.0.9</p></li><li class="listitem"><p>GCC 4.2.1: libstdc++.so.6.0.9 (See Note 3)</p></li><li class="listitem"><p>GCC 4.2.2: libstdc++.so.6.0.9</p></li><li class="listitem"><p>GCC 4.3.0: libstdc++.so.6.0.10</p></li><li class="listitem"><p>GCC 4.4.0: libstdc++.so.6.0.11</p></li><li class="listitem"><p>GCC 4.4.1: libstdc++.so.6.0.12</p></li><li class="listitem"><p>GCC 4.4.2: libstdc++.so.6.0.13</p></li><li class="listitem"><p>GCC 4.5.0: libstdc++.so.6.0.14</p></li><li class="listitem"><p>GCC 4.6.0: libstdc++.so.6.0.15</p></li><li class="listitem"><p>GCC 4.6.1: libstdc++.so.6.0.16</p></li><li class="listitem"><p>GCC 4.7.0: libstdc++.so.6.0.17</p></li><li class="listitem"><p>GCC 4.8.0: libstdc++.so.6.0.18</p></li><li class="listitem"><p>GCC 4.8.3: libstdc++.so.6.0.19</p></li><li class="listitem"><p>GCC 4.9.0: libstdc++.so.6.0.20</p></li><li class="listitem"><p>GCC 5.1.0: libstdc++.so.6.0.21</p></li><li class="listitem"><p>GCC 6.1.0: libstdc++.so.6.0.22</p></li><li class="listitem"><p>GCC 7.1.0: libstdc++.so.6.0.23</p></li><li class="listitem"><p>GCC 7.2.0: libstdc++.so.6.0.24</p></li><li class="listitem"><p>GCC 8.1.0: libstdc++.so.6.0.25</p></li><li class="listitem"><p>GCC 9.1.0: libstdc++.so.6.0.26</p></li><li class="listitem"><p>GCC 9.2.0: libstdc++.so.6.0.27</p></li><li class="listitem"><p>GCC 9.3.0: libstdc++.so.6.0.28</p></li><li class="listitem"><p>GCC 10.1.0: libstdc++.so.6.0.28</p></li><li class="listitem"><p>GCC 11.1.0: libstdc++.so.6.0.29</p></li><li class="listitem"><p>GCC 12.1.0: libstdc++.so.6.0.30</p></li></ul></div><p> 114 Note 1: Error should be libstdc++.so.3.0.3. 115 </p><p> 116 Note 2: Not strictly required. 117 </p><p> 118 Note 3: This release (but not previous or subsequent) has one 119 known incompatibility, see <a class="link" href="http://gcc.gnu.org/bugzilla/show_bug.cgi?id=33678" target="_top">33678</a> 120 in the GCC bug database. 121 </p></li><li class="listitem"><p>Symbol versioning on the libstdc++.so binary.</p><p>mapfile: libstdc++-v3/config/abi/pre/gnu.ver</p><p>It is versioned with the following labels and version 122 definitions, where the version definition is the maximum for a 123 particular release. Note, only symbols which are newly introduced 124 will use the maximum version definition. Thus, for release series 125 with the same label, but incremented version definitions, the later 126 release has both versions. (An example of this would be the 127 GCC 3.2.1 release, which has GLIBCPP_3.2.1 for new symbols and 128 GLIBCPP_3.2 for symbols that were introduced in the GCC 3.2.0 129 release.) If a particular release is not listed, it has the same 130 version labels as the preceding release. 131 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>GCC 3.0.0: (Error, not versioned)</p></li><li class="listitem"><p>GCC 3.0.1: (Error, not versioned)</p></li><li class="listitem"><p>GCC 3.0.2: (Error, not versioned)</p></li><li class="listitem"><p>GCC 3.0.3: (Error, not versioned)</p></li><li class="listitem"><p>GCC 3.0.4: (Error, not versioned)</p></li><li class="listitem"><p>GCC 3.1.0: GLIBCPP_3.1, CXXABI_1</p></li><li class="listitem"><p>GCC 3.1.1: GLIBCPP_3.1, CXXABI_1</p></li><li class="listitem"><p>GCC 3.2.0: GLIBCPP_3.2, CXXABI_1.2</p></li><li class="listitem"><p>GCC 3.2.1: GLIBCPP_3.2.1, CXXABI_1.2</p></li><li class="listitem"><p>GCC 3.2.2: GLIBCPP_3.2.2, CXXABI_1.2</p></li><li class="listitem"><p>GCC 3.2.3: GLIBCPP_3.2.2, CXXABI_1.2</p></li><li class="listitem"><p>GCC 3.3.0: GLIBCPP_3.2.2, CXXABI_1.2.1</p></li><li class="listitem"><p>GCC 3.3.1: GLIBCPP_3.2.3, CXXABI_1.2.1</p></li><li class="listitem"><p>GCC 3.3.2: GLIBCPP_3.2.3, CXXABI_1.2.1</p></li><li class="listitem"><p>GCC 3.3.3: GLIBCPP_3.2.3, CXXABI_1.2.1</p></li><li class="listitem"><p>GCC 3.4.0: GLIBCXX_3.4, CXXABI_1.3</p></li><li class="listitem"><p>GCC 3.4.1: GLIBCXX_3.4.1, CXXABI_1.3</p></li><li class="listitem"><p>GCC 3.4.2: GLIBCXX_3.4.2</p></li><li class="listitem"><p>GCC 3.4.3: GLIBCXX_3.4.3</p></li><li class="listitem"><p>GCC 4.0.0: GLIBCXX_3.4.4, CXXABI_1.3.1</p></li><li class="listitem"><p>GCC 4.0.1: GLIBCXX_3.4.5</p></li><li class="listitem"><p>GCC 4.0.2: GLIBCXX_3.4.6</p></li><li class="listitem"><p>GCC 4.0.3: GLIBCXX_3.4.7</p></li><li class="listitem"><p>GCC 4.1.1: GLIBCXX_3.4.8</p></li><li class="listitem"><p>GCC 4.2.0: GLIBCXX_3.4.9</p></li><li class="listitem"><p>GCC 4.3.0: GLIBCXX_3.4.10, CXXABI_1.3.2</p></li><li class="listitem"><p>GCC 4.4.0: GLIBCXX_3.4.11, CXXABI_1.3.3</p></li><li class="listitem"><p>GCC 4.4.1: GLIBCXX_3.4.12, CXXABI_1.3.3</p></li><li class="listitem"><p>GCC 4.4.2: GLIBCXX_3.4.13, CXXABI_1.3.3</p></li><li class="listitem"><p>GCC 4.5.0: GLIBCXX_3.4.14, CXXABI_1.3.4</p></li><li class="listitem"><p>GCC 4.6.0: GLIBCXX_3.4.15, CXXABI_1.3.5</p></li><li class="listitem"><p>GCC 4.6.1: GLIBCXX_3.4.16, CXXABI_1.3.5</p></li><li class="listitem"><p>GCC 4.7.0: GLIBCXX_3.4.17, CXXABI_1.3.6</p></li><li class="listitem"><p>GCC 4.8.0: GLIBCXX_3.4.18, CXXABI_1.3.7</p></li><li class="listitem"><p>GCC 4.8.3: GLIBCXX_3.4.19, CXXABI_1.3.7</p></li><li class="listitem"><p>GCC 4.9.0: GLIBCXX_3.4.20, CXXABI_1.3.8</p></li><li class="listitem"><p>GCC 5.1.0: GLIBCXX_3.4.21, CXXABI_1.3.9</p></li><li class="listitem"><p>GCC 6.1.0: GLIBCXX_3.4.22, CXXABI_1.3.10</p></li><li class="listitem"><p>GCC 7.1.0: GLIBCXX_3.4.23, CXXABI_1.3.11</p></li><li class="listitem"><p>GCC 7.2.0: GLIBCXX_3.4.24, CXXABI_1.3.11</p></li><li class="listitem"><p>GCC 8.1.0: GLIBCXX_3.4.25, CXXABI_1.3.11</p></li><li class="listitem"><p>GCC 9.1.0: GLIBCXX_3.4.26, CXXABI_1.3.12</p></li><li class="listitem"><p>GCC 9.2.0: GLIBCXX_3.4.27, CXXABI_1.3.12</p></li><li class="listitem"><p>GCC 9.3.0: GLIBCXX_3.4.28, CXXABI_1.3.12</p></li><li class="listitem"><p>GCC 10.1.0: GLIBCXX_3.4.28, CXXABI_1.3.12</p></li><li class="listitem"><p>GCC 11.1.0: GLIBCXX_3.4.29, CXXABI_1.3.13</p></li><li class="listitem"><p>GCC 12.1.0: GLIBCXX_3.4.30, CXXABI_1.3.13</p></li></ul></div></li><li class="listitem"><p>Incremental bumping of a compiler pre-defined macro, 132 __GXX_ABI_VERSION. This macro is defined as the version of the 133 compiler v3 ABI, with g++ 3.0 being version 100. This macro will 134 be automatically defined whenever g++ is used (the curious can 135 test this by invoking g++ with the '-v' flag.) 136 </p><p> 137 This macro was defined in the file "lang-specs.h" in the gcc/cp directory. 138 Later versions defined it in "c-common.c" in the gcc directory, and from 139 G++ 3.4 it is defined in c-cppbuiltin.c and its value determined by the 140 '-fabi-version' command line option. 141 </p><p> 142 It is versioned as follows, where 'n' is given by '-fabi-version=n': 143 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>GCC 3.0: 100</p></li><li class="listitem"><p>GCC 3.1: 100 (Error, should be 101)</p></li><li class="listitem"><p>GCC 3.2: 102</p></li><li class="listitem"><p>GCC 3.3: 102</p></li><li class="listitem"><p>GCC 3.4, GCC 4.x: 102 (when n=1)</p></li><li class="listitem"><p>GCC 3.4, GCC 4.x: 1000 + n (when n>1) </p></li><li class="listitem"><p>GCC 3.4, GCC 4.x: 999999 (when n=0)</p></li></ul></div><p></p></li><li class="listitem"><p>Changes to the default compiler option for 144 <code class="code">-fabi-version</code>. 145 </p><p> 146 It is versioned as follows: 147 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>GCC 3.0: (Error, not versioned) </p></li><li class="listitem"><p>GCC 3.1: (Error, not versioned) </p></li><li class="listitem"><p>GCC 3.2: <code class="code">-fabi-version=1</code></p></li><li class="listitem"><p>GCC 3.3: <code class="code">-fabi-version=1</code></p></li><li class="listitem"><p>GCC 3.4, GCC 4.x: <code class="code">-fabi-version=2</code> <span class="emphasis"><em>(Incompatible with previous)</em></span></p></li><li class="listitem"><p>GCC 5 and higher: <code class="code">-fabi-version=0</code> <span class="emphasis"><em>(See GCC manual for meaning)</em></span></p></li></ul></div><p></p></li><li class="listitem"><p><a id="abi.versioning.__GLIBCXX__"></a>Incremental bumping of a library pre-defined macro. For releases 148 before 3.4.0, the macro is <span class="symbol">__GLIBCPP__</span>. For later 149 releases, it's <span class="symbol">__GLIBCXX__</span>. (The libstdc++ project 150 generously changed from CPP to CXX throughout its source to allow the 151 "C" pre-processor the CPP macro namespace.) These macros are defined 152 as the date the library was released, in compressed ISO date format, 153 as an integer constant. 154 </p><p> 155 This macro is defined in the file 156 <code class="filename">c++config</code> in the 157 <code class="filename">libstdc++-v3/include/bits</code> 158 directory. Up to GCC 4.1.0, it was 159 changed every night by an automated script. Since GCC 4.1.0 it is set 160 during configuration to the same value as 161 <code class="filename">gcc/DATESTAMP</code>, so for an official release its value 162 is the same as the date of the release, which is given in the <a class="link" href="https://gcc.gnu.org/develop.html#timeline" target="_top">GCC Release 163 Timeline</a>. 164 </p><p> 165 This macro can be used in code to detect whether the C++ Standard Library 166 implementation in use is libstdc++, but is not useful for detecting the 167 libstdc++ version, nor whether particular features are supported. 168 The macro value might be a date after a feature was added to the 169 development trunk, but the release could be from an older branch without 170 the feature. For example, in the 5.4.0 release the macro has the value 171 <code class="literal">20160603</code> which is greater than the 172 <code class="literal">20160427</code> value of the macro in the 6.1.0 release, 173 but there are features supported in the 6.1.0 release that are not 174 supported in the 5.4.0 release. 175 You also can't test for the exact values listed below to try and 176 identify a release, because a snapshot taken from the gcc-5-branch on 177 2016-04-27 would have the same value for the macro as the 6.1.0 release 178 despite being a different version. 179 Many GNU/Linux distributions build their GCC packages from snapshots, so 180 the macro can have dates that don't correspond to official releases. 181 </p><p> 182 It is versioned as follows: 183 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>GCC 3.0.0: <code class="literal">20010615</code></p></li><li class="listitem"><p>GCC 3.0.1: <code class="literal">20010819</code></p></li><li class="listitem"><p>GCC 3.0.2: <code class="literal">20011023</code></p></li><li class="listitem"><p>GCC 3.0.3: <code class="literal">20011220</code></p></li><li class="listitem"><p>GCC 3.0.4: <code class="literal">20020220</code></p></li><li class="listitem"><p>GCC 3.1.0: <code class="literal">20020514</code></p></li><li class="listitem"><p>GCC 3.1.1: <code class="literal">20020725</code></p></li><li class="listitem"><p>GCC 3.2.0: <code class="literal">20020814</code></p></li><li class="listitem"><p>GCC 3.2.1: <code class="literal">20021119</code></p></li><li class="listitem"><p>GCC 3.2.2: <code class="literal">20030205</code></p></li><li class="listitem"><p>GCC 3.2.3: <code class="literal">20030422</code></p></li><li class="listitem"><p>GCC 3.3.0: <code class="literal">20030513</code></p></li><li class="listitem"><p>GCC 3.3.1: <code class="literal">20030804</code></p></li><li class="listitem"><p>GCC 3.3.2: <code class="literal">20031016</code></p></li><li class="listitem"><p>GCC 3.3.3: <code class="literal">20040214</code></p></li><li class="listitem"><p>GCC 3.4.0: <code class="literal">20040419</code></p></li><li class="listitem"><p>GCC 3.4.1: <code class="literal">20040701</code></p></li><li class="listitem"><p>GCC 3.4.2: <code class="literal">20040906</code></p></li><li class="listitem"><p>GCC 3.4.3: <code class="literal">20041105</code></p></li><li class="listitem"><p>GCC 3.4.4: <code class="literal">20050519</code></p></li><li class="listitem"><p>GCC 3.4.5: <code class="literal">20051201</code></p></li><li class="listitem"><p>GCC 3.4.6: <code class="literal">20060306</code></p></li><li class="listitem"><p>GCC 4.0.0: <code class="literal">20050421</code></p></li><li class="listitem"><p>GCC 4.0.1: <code class="literal">20050707</code></p></li><li class="listitem"><p>GCC 4.0.2: <code class="literal">20050921</code></p></li><li class="listitem"><p>GCC 4.0.3: <code class="literal">20060309</code></p></li><li class="listitem"><p> 184 GCC 4.1.0 and later: the GCC release date, as shown in the 185 <a class="link" href="https://gcc.gnu.org/develop.html#timeline" target="_top">GCC 186 Release Timeline</a> 187 </p></li></ul></div><p></p></li><li class="listitem"><p> 188 Since GCC 7, incremental bumping of a library pre-defined macro, 189 <span class="symbol">_GLIBCXX_RELEASE</span>. This macro is defined to the GCC 190 major version that the libstdc++ headers belong to, as an integer constant. 191 When compiling with GCC it has the same value as GCC's pre-defined 192 macro <span class="symbol">__GNUC__</span>. 193 This macro can be used when libstdc++ is used with a non-GNU 194 compiler where <span class="symbol">__GNUC__</span> is not defined, or has a 195 different value that doesn't correspond to the libstdc++ version. 196 </p><p> 197 This macro is defined in the file 198 <code class="filename">c++config</code> in the 199 <code class="filename">libstdc++-v3/include/bits</code> 200 directory and is generated automatically by autoconf as part of the 201 configure-time generation of 202 <code class="filename">config.h</code> and subsequently 203 <code class="filename"><bits/c++config.h></code>. 204 </p></li><li class="listitem"><p> 205 Historically, incremental bumping of a library pre-defined macro, 206 <span class="symbol">_GLIBCPP_VERSION</span>. This macro was defined as the 207 released version of the library, as a string literal. This was only 208 implemented in GCC 3.1.0 releases and higher, and was deprecated in 209 3.4.x (where it was called <span class="symbol">_GLIBCXX_VERSION</span>), 210 and is not defined in 4.0.0 and higher. 211 </p><p> 212 This macro is defined in the same file as 213 <span class="symbol">_GLIBCXX_RELEASE</span>, described above. 214 </p><p> 215 It is versioned as follows: 216 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>GCC 3.0.0: <code class="literal">"3.0.0"</code></p></li><li class="listitem"><p>GCC 3.0.1: <code class="literal">"3.0.0"</code> (Error, should be <code class="literal">"3.0.1"</code>)</p></li><li class="listitem"><p>GCC 3.0.2: <code class="literal">"3.0.0"</code> (Error, should be <code class="literal">"3.0.2"</code>)</p></li><li class="listitem"><p>GCC 3.0.3: <code class="literal">"3.0.0"</code> (Error, should be <code class="literal">"3.0.3"</code>)</p></li><li class="listitem"><p>GCC 3.0.4: <code class="literal">"3.0.0"</code> (Error, should be <code class="literal">"3.0.4"</code>)</p></li><li class="listitem"><p>GCC 3.1.0: <code class="literal">"3.1.0"</code></p></li><li class="listitem"><p>GCC 3.1.1: <code class="literal">"3.1.1"</code></p></li><li class="listitem"><p>GCC 3.2.0: <code class="literal">"3.2"</code></p></li><li class="listitem"><p>GCC 3.2.1: <code class="literal">"3.2.1"</code></p></li><li class="listitem"><p>GCC 3.2.2: <code class="literal">"3.2.2"</code></p></li><li class="listitem"><p>GCC 3.2.3: <code class="literal">"3.2.3"</code></p></li><li class="listitem"><p>GCC 3.3.0: <code class="literal">"3.3"</code></p></li><li class="listitem"><p>GCC 3.3.1: <code class="literal">"3.3.1"</code></p></li><li class="listitem"><p>GCC 3.3.2: <code class="literal">"3.3.2"</code></p></li><li class="listitem"><p>GCC 3.3.3: <code class="literal">"3.3.3"</code></p></li><li class="listitem"><p>GCC 3.4: <code class="literal">"version-unused"</code></p></li><li class="listitem"><p>GCC 4 and later: not defined</p></li></ul></div><p></p></li><li class="listitem"><p> 217 Matching each specific C++ compiler release to a specific set of 218 C++ include files. This is only implemented in GCC 3.1.1 releases 219 and higher. 220 </p><p> 221 All C++ includes are installed in 222 <code class="filename">include/c++</code>, then nested in a 223 directory hierarchy corresponding to the C++ compiler's released 224 version. This version corresponds to the variable "gcc_version" in 225 "libstdc++-v3/acinclude.m4," and more details can be found in that 226 file's macro GLIBCXX_CONFIGURE (GLIBCPP_CONFIGURE before GCC 3.4.0). 227 </p><p> 228 C++ includes are versioned as follows: 229 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>GCC 3.0.0: include/g++-v3</p></li><li class="listitem"><p>GCC 3.0.1: include/g++-v3</p></li><li class="listitem"><p>GCC 3.0.2: include/g++-v3</p></li><li class="listitem"><p>GCC 3.0.3: include/g++-v3</p></li><li class="listitem"><p>GCC 3.0.4: include/g++-v3</p></li><li class="listitem"><p>GCC 3.1.0: include/g++-v3</p></li><li class="listitem"><p>GCC 3.1.1: include/c++/3.1.1</p></li><li class="listitem"><p>GCC 3.2.0: include/c++/3.2</p></li><li class="listitem"><p>GCC 3.2.1: include/c++/3.2.1</p></li><li class="listitem"><p>GCC 3.2.2: include/c++/3.2.2</p></li><li class="listitem"><p>GCC 3.2.3: include/c++/3.2.3</p></li><li class="listitem"><p>GCC 3.3.0: include/c++/3.3</p></li><li class="listitem"><p>GCC 3.3.1: include/c++/3.3.1</p></li><li class="listitem"><p>GCC 3.3.2: include/c++/3.3.2</p></li><li class="listitem"><p>GCC 3.3.3: include/c++/3.3.3</p></li><li class="listitem"><p>GCC 3.4.x: include/c++/3.4.x</p></li><li class="listitem"><p>GCC 4.x.y: include/c++/4.x.y</p></li><li class="listitem"><p>GCC 5.1.0: include/c++/5.1.0</p></li><li class="listitem"><p>GCC x.y.0: include/c++/x.y.0 (for releases after GCC 5.1.0)</p></li></ul></div><p></p></li></ol></div><p> 230 Taken together, these techniques can accurately specify interface 231 and implementation changes in the GNU C++ tools themselves. Used 232 properly, they allow both the GNU C++ tools implementation, and 233 programs using them, an evolving yet controlled development that 234 maintains backward compatibility. 235</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="abi.versioning.prereq"></a>Prerequisites</h4></div></div></div><p> 236 Minimum environment that supports a versioned ABI: A supported 237 dynamic linker, a GNU linker of sufficient vintage to understand 238 demangled C++ name globbing (ld) or the Sun linker, a shared 239 executable compiled 240 with g++, and shared libraries (libgcc_s, libstdc++) compiled by 241 a compiler (g++) with a compatible ABI. Phew. 242 </p><p> 243 On top of all that, an additional constraint: libstdc++ did not 244 attempt to version symbols (or age gracefully, really) until 245 version 3.1.0. 246 </p><p> 247 Most modern GNU/Linux and BSD versions, particularly ones using 248 GCC 3.1 and later, will meet the 249 requirements above, as does Solaris 2.5 and up. 250 </p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="abi.versioning.config"></a>Configuring</h4></div></div></div><p> 251 It turns out that most of the configure options that change 252 default behavior will impact the mangled names of exported 253 symbols, and thus impact versioning and compatibility. 254 </p><p> 255 For more information on configure options, including ABI 256 impacts, see: 257 <a class="link" href="configure.html" title="Configure">here</a> 258 </p><p> 259 There is one flag that explicitly deals with symbol versioning: 260 --enable-symvers. 261 </p><p> 262 In particular, libstdc++-v3/acinclude.m4 has a macro called 263 GLIBCXX_ENABLE_SYMVERS that defaults to yes (or the argument 264 passed in via --enable-symvers=foo). At that point, the macro 265 attempts to make sure that all the requirement for symbol 266 versioning are in place. For more information, please consult 267 acinclude.m4. 268 </p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="abi.versioning.active"></a>Checking Active</h4></div></div></div><p> 269 When the GNU C++ library is being built with symbol versioning 270 on, you should see the following at configure time for 271 libstdc++ (showing either 'gnu' or another of the supported styles): 272 </p><pre class="screen"> 273<code class="computeroutput"> 274 checking versioning on shared library symbols... gnu 275</code> 276</pre><p> 277 If you don't see this line in the configure output, or if this line 278 appears but the last word is 'no', then you are out of luck. 279</p><p> 280 If the compiler is pre-installed, a quick way to test is to compile 281 the following (or any) simple C++ file and link it to the shared 282 libstdc++ library: 283</p><pre class="programlisting"> 284#include <iostream> 285 286int main() 287{ std::cout << "hello" << std::endl; return 0; } 288 289%g++ hello.cc -o hello.out 290 291%ldd hello.out 292 libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0x00764000) 293 libm.so.6 => /lib/tls/libm.so.6 (0x004a8000) 294 libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40016000) 295 libc.so.6 => /lib/tls/libc.so.6 (0x0036d000) 296 /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000) 297 298%nm hello.out 299</pre><p> 300If you see symbols in the resulting output with "GLIBCXX_3" as part 301of the name, then the executable is versioned. Here's an example: 302</p><p> 303 <code class="code">U _ZNSt8ios_base4InitC1Ev@@GLIBCXX_3.4</code> 304</p><p> 305On Solaris 2, you can use <code class="code">pvs -r</code> instead: 306</p><pre class="programlisting"> 307%g++ hello.cc -o hello.out 308 309%pvs -r hello.out 310 libstdc++.so.6 (GLIBCXX_3.4, GLIBCXX_3.4.12); 311 libgcc_s.so.1 (GCC_3.0); 312 libc.so.1 (SUNWprivate_1.1, SYSVABI_1.3); 313</pre><p> 314<code class="code">ldd -v</code> works too, but is very verbose. 315</p></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="abi.changes_allowed"></a>Allowed Changes</h3></div></div></div><p> 316The following will cause the library minor version number to 317increase, say from "libstdc++.so.3.0.4" to "libstdc++.so.3.0.5". 318</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Adding an exported global or static data member</p></li><li class="listitem"><p>Adding an exported function, static or non-virtual member function</p></li><li class="listitem"><p>Adding an exported symbol or symbols by additional instantiations</p></li></ol></div><p> 319Other allowed changes are possible. 320</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="abi.changes_no"></a>Prohibited Changes</h3></div></div></div><p> 321The following non-exhaustive list will cause the library major version 322number to increase, say from "libstdc++.so.3.0.4" to 323"libstdc++.so.4.0.0". 324</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Changes in the gcc/g++ compiler ABI</p></li><li class="listitem"><p>Changing size of an exported symbol</p></li><li class="listitem"><p>Changing alignment of an exported symbol</p></li><li class="listitem"><p>Changing the layout of an exported symbol</p></li><li class="listitem"><p>Changing mangling on an exported symbol</p></li><li class="listitem"><p>Deleting an exported symbol</p></li><li class="listitem"><p>Changing the inheritance properties of a type by adding or removing 325 base classes</p></li><li class="listitem"><p> 326 Changing the size, alignment, or layout of types 327 specified in the C++ standard. These may not necessarily be 328 instantiated or otherwise exported in the library binary, and 329 include all the required locale facets, as well as things like 330 std::basic_streambuf, et al. 331</p></li><li class="listitem"><p> Adding an explicit copy constructor or destructor to a 332class that would otherwise have implicit versions. This will change 333the way the compiler deals with this class in by-value return 334statements or parameters: instead of passing instances of this 335class in registers, the compiler will be forced to use memory. See the 336section on <a class="link" href="https://itanium-cxx-abi.github.io/cxx-abi/abi.html#calls" target="_top">Function 337Calling Conventions and APIs</a> 338 of the C++ ABI documentation for further details. 339</p></li></ol></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="abi.impl"></a>Implementation</h3></div></div></div><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> 340 Separation of interface and implementation 341 </p><p> 342 This is accomplished by two techniques that separate the API from 343 the ABI: forcing undefined references to link against a library 344 binary for definitions. 345 </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Include files have declarations, source files have defines</span></dt><dd><p> 346 For non-templatized types, such as much of <code class="code">class 347 locale</code>, the appropriate standard C++ include, say 348 <code class="code">locale</code>, can contain full declarations, while 349 various source files (say <code class="code"> locale.cc, locale_init.cc, 350 localename.cc</code>) contain definitions. 351 </p></dd><dt><span class="term">Extern template on required types</span></dt><dd><p> 352 For parts of the standard that have an explicit list of 353 required instantiations, the GNU extension syntax <code class="code"> extern 354 template </code> can be used to control where template 355 definitions reside. By marking required instantiations as 356 <code class="code"> extern template </code> in include files, and providing 357 explicit instantiations in the appropriate instantiation files, 358 non-inlined template functions can be versioned. This technique 359 is mostly used on parts of the standard that require <code class="code"> 360 char</code> and <code class="code"> wchar_t</code> instantiations, and 361 includes <code class="code"> basic_string</code>, the locale facets, and the 362 types in <code class="code"> iostreams</code>. 363 </p></dd></dl></div><p> 364 In addition, these techniques have the additional benefit that they 365 reduce binary size, which can increase runtime performance. 366 </p></li><li class="listitem"><p> 367 Namespaces linking symbol definitions to export mapfiles 368 </p><p> 369 All symbols in the shared library binary are processed by a 370 linker script at build time that either allows or disallows 371 external linkage. Because of this, some symbols, regardless of 372 normal C/C++ linkage, are not visible. Symbols that are internal 373 have several appealing characteristics: by not exporting the 374 symbols, there are no relocations when the shared library is 375 started and thus this makes for faster runtime loading 376 performance by the underlying dynamic loading mechanism. In 377 addition, they have the possibility of changing without impacting 378 ABI compatibility. 379 </p><p>The following namespaces are transformed by the mapfile:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="code">namespace std</code></span></dt><dd><p> Defaults to exporting all symbols in label 380<code class="code">GLIBCXX</code> that do not begin with an underscore, i.e., 381<code class="code">__test_func</code> would not be exported by default. Select 382exceptional symbols are allowed to be visible.</p></dd><dt><span class="term"><code class="code">namespace __gnu_cxx</code></span></dt><dd><p> Defaults to not exporting any symbols in label 383<code class="code">GLIBCXX</code>, select items are allowed to be visible.</p></dd><dt><span class="term"><code class="code">namespace __gnu_internal</code></span></dt><dd><p> Defaults to not exported, no items are allowed to be visible.</p></dd><dt><span class="term"><code class="code">namespace __cxxabiv1</code>, aliased to <code class="code"> namespace abi</code></span></dt><dd><p> Defaults to not exporting any symbols in label 384<code class="code">CXXABI</code>, select items are allowed to be visible.</p></dd></dl></div><p> 385</p></li><li class="listitem"><p>Freezing the API</p><p>Disallowed changes, as above, are not made on a stable release 386branch. Enforcement tends to be less strict with GNU extensions that 387standard includes.</p></li></ol></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="abi.testing"></a>Testing</h3></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="abi.testing.single"></a>Single ABI Testing</h4></div></div></div><p> 388 Testing for GNU C++ ABI changes is composed of two distinct 389 areas: testing the C++ compiler (g++) for compiler changes, and 390 testing the C++ library (libstdc++) for library changes. 391 </p><p> 392 Testing the C++ compiler ABI can be done various ways. 393 </p><p> 394 One. Intel ABI checker. 395 </p><p> 396Two. 397The second is yet unreleased, but has been announced on the gcc 398mailing list. It is yet unspecified if these tools will be freely 399available, and able to be included in a GNU project. Please contact 400Mark Mitchell (mark@codesourcery.com) for more details, and current 401status. 402</p><p> 403Three. 404Involves using the vlad.consistency test framework. This has also been 405discussed on the gcc mailing lists. 406</p><p> 407Testing the C++ library ABI can also be done various ways. 408</p><p> 409One. 410(Brendan Kehoe, Jeff Law suggestion to run 'make check-c++' two ways, 411one with a new compiler and an old library, and the other with an old 412compiler and a new library, and look for testsuite regressions) 413</p><p> 414Details on how to set this kind of test up can be found here: 415http://gcc.gnu.org/ml/gcc/2002-08/msg00142.html 416</p><p> 417Two. 418Use the 'make check-abi' rule in the libstdc++ Makefile. 419</p><p> 420This is a proactive check of the library ABI. Currently, exported symbol 421names that are either weak or defined are checked against a last known 422good baseline. Currently, this baseline is keyed off of 3.4.0 423binaries, as this was the last time the .so number was incremented. In 424addition, all exported names are demangled, and the exported objects 425are checked to make sure they are the same size as the same object in 426the baseline. 427 428Notice that each baseline is relative to a <span class="emphasis"><em>default</em></span> 429configured library and compiler: in particular, if options such as 430--enable-clocale, or --with-cpu, in case of multilibs, are used at 431configure time, the check may fail, either because of substantive 432differences or because of limitations of the current checking 433machinery. 434</p><p> 435This dataset is insufficient, yet a start. Also needed is a 436comprehensive check for all user-visible types part of the standard 437library for sizeof() and alignof() changes. 438</p><p> 439Verifying compatible layouts of objects is not even attempted. It 440should be possible to use sizeof, alignof, and offsetof to compute 441offsets for each structure and type in the standard library, saving to 442another datafile. Then, compute this in a similar way for new 443binaries, and look for differences. 444</p><p> 445Another approach might be to use the -fdump-class-hierarchy flag to 446get information. However, currently this approach gives insufficient 447data for use in library testing, as class data members, their offsets, 448and other detailed data is not displayed with this flag. 449(See PR g++/7470 on how this was used to find bugs.) 450</p><p> 451Perhaps there are other C++ ABI checkers. If so, please notify 452us. We'd like to know about them! 453</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="abi.testing.multi"></a>Multiple ABI Testing</h4></div></div></div><p> 454A "C" application, dynamically linked to two shared libraries, liba, 455libb. The dependent library liba is a C++ shared library compiled with 456GCC 3.3, and uses io, exceptions, locale, etc. The dependent library 457libb is a C++ shared library compiled with GCC 3.4, and also uses io, 458exceptions, locale, etc. 459</p><p> As above, libone is constructed as follows: </p><pre class="programlisting"> 460%$bld/H-x86-gcc-3.4.0/bin/g++ -fPIC -DPIC -c a.cc 461 462%$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 463 464%ln -s libone.so.1.0.0 libone.so 465 466%$bld/H-x86-gcc-3.4.0/bin/g++ -c a.cc 467 468%ar cru libone.a a.o 469</pre><p> And, libtwo is constructed as follows: </p><pre class="programlisting"> 470%$bld/H-x86-gcc-3.3.3/bin/g++ -fPIC -DPIC -c b.cc 471 472%$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 473 474%ln -s libtwo.so.1.0.0 libtwo.so 475 476%$bld/H-x86-gcc-3.3.3/bin/g++ -c b.cc 477 478%ar cru libtwo.a b.o 479</pre><p> ...with the resulting libraries looking like </p><pre class="screen"> 480<code class="computeroutput"> 481%ldd libone.so.1.0.0 482 libstdc++.so.6 => /usr/lib/libstdc++.so.6 (0x40016000) 483 libm.so.6 => /lib/tls/libm.so.6 (0x400fa000) 484 libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x4011c000) 485 libc.so.6 => /lib/tls/libc.so.6 (0x40125000) 486 /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000) 487 488%ldd libtwo.so.1.0.0 489 libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0x40027000) 490 libm.so.6 => /lib/tls/libm.so.6 (0x400e1000) 491 libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40103000) 492 libc.so.6 => /lib/tls/libc.so.6 (0x4010c000) 493 /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000) 494</code> 495</pre><p> 496 Then, the "C" compiler is used to compile a source file that uses 497 functions from each library. 498</p><pre class="programlisting"> 499gcc test.c -g -O2 -L. -lone -ltwo /usr/lib/libstdc++.so.5 /usr/lib/libstdc++.so.6 500</pre><p> 501 Which gives the expected: 502</p><pre class="screen"> 503<code class="computeroutput"> 504%ldd a.out 505 libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0x00764000) 506 libstdc++.so.6 => /usr/lib/libstdc++.so.6 (0x40015000) 507 libc.so.6 => /lib/tls/libc.so.6 (0x0036d000) 508 libm.so.6 => /lib/tls/libm.so.6 (0x004a8000) 509 libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x400e5000) 510 /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000) 511</code> 512</pre><p> 513 This resulting binary, when executed, will be able to safely use 514 code from both liba, and the dependent libstdc++.so.6, and libb, 515 with the dependent libstdc++.so.5. 516</p></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="abi.issues"></a>Outstanding Issues</h3></div></div></div><p> 517 Some features in the C++ language make versioning especially 518 difficult. In particular, compiler generated constructs such as 519 implicit instantiations for templates, typeinfo information, and 520 virtual tables all may cause ABI leakage across shared library 521 boundaries. Because of this, mixing C++ ABIs is not recommended at 522 this time. 523</p><p> 524 For more background on this issue, see these bugzilla entries: 525</p><p> 526<a class="link" href="http://gcc.gnu.org/PR24660" target="_top">24660: versioning weak symbols in libstdc++</a> 527</p><p> 528<a class="link" href="http://gcc.gnu.org/PR19664" target="_top">19664: libstdc++ headers should have pop/push of the visibility around the declarations</a> 529</p></div><div class="bibliography"><div class="titlepage"><div><div><h3 class="title"><a id="abi.biblio"></a>Bibliography</h3></div></div></div><div class="biblioentry"><a id="biblio.abicheck"></a><p>[biblio.abicheck] <span class="title"><em> 530 <a class="link" href="http://abicheck.sourceforge.net" target="_top"> 531 ABIcheck 532 </a> 533 </em>. </span></p></div><div class="biblioentry"><a id="biblio.cxxabi"></a><p>[biblio.cxxabi] <span class="title"><em> 534 <a class="link" href="https://itanium-cxx-abi.github.io/cxx-abi/" target="_top"> 535 Itanium C++ ABI 536 </a> 537 </em>. </span></p></div><div class="biblioentry"><a id="id-1.3.6.3.6.10.4"></a><p><span class="title"><em> 538 <a class="link" href="https://docs.oracle.com/cd/E23824_01/html/819-0690/index.html" target="_top"> 539 Linker and Libraries Guide (document 819-0690) 540 </a> 541 </em>. </span></p></div><div class="biblioentry"><a id="id-1.3.6.3.6.10.5"></a><p><span class="title"><em> 542 <a class="link" href="https://docs.oracle.com/cd/E19422-01/819-3689/" target="_top"> 543 Sun Studio 11: C++ Migration Guide (document 819-3689) 544 </a> 545 </em>. </span></p></div><div class="biblioentry"><a id="id-1.3.6.3.6.10.6"></a><p><span class="title"><em> 546 <a class="link" href="https://www.akkadia.org/drepper/dsohowto.pdf" target="_top"> 547 How to Write Shared Libraries 548 </a> 549 </em>. </span><span class="author"><span class="firstname">Ulrich</span> <span class="surname">Drepper</span>. </span></p></div><div class="biblioentry"><a id="id-1.3.6.3.6.10.7"></a><p><span class="title"><em> 550 <a class="link" href="https://developer.arm.com/documentation/ihi0036/latest/" target="_top"> 551 C++ ABI for the ARM Architecture 552 </a> 553 </em>. </span></p></div><div class="biblioentry"><a id="id-1.3.6.3.6.10.8"></a><p><span class="title"><em> 554 <a class="link" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1976.html" target="_top"> 555 Dynamic Shared Objects: Survey and Issues 556 </a> 557 </em>. </span><span class="subtitle"> 558 ISO C++ J16/06-0046 559 . </span><span class="author"><span class="firstname">Benjamin</span> <span class="surname">Kosnik</span>. </span></p></div><div class="biblioentry"><a id="id-1.3.6.3.6.10.9"></a><p><span class="title"><em> 560 <a class="link" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n2013.html" target="_top"> 561 Versioning With Namespaces 562 </a> 563 </em>. </span><span class="subtitle"> 564 ISO C++ J16/06-0083 565 . </span><span class="author"><span class="firstname">Benjamin</span> <span class="surname">Kosnik</span>. </span></p></div><div class="biblioentry"><a id="id-1.3.6.3.6.10.10"></a><p><span class="title"><em> 566 <a class="link" href="http://syrcose.ispras.ru/2009/files/02_paper.pdf" target="_top"> 567 Binary Compatibility of Shared Libraries Implemented in C++ 568 on GNU/Linux Systems 569 </a> 570 </em>. </span><span class="subtitle"> 571 SYRCoSE 2009 572 . </span><span class="author"><span class="firstname">Pavel</span> <span class="surname">Shved</span>. </span><span class="author"><span class="firstname">Denis</span> <span class="surname">Silakov</span>. </span></p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="test.html">Prev</a>��</td><td width="20%" align="center"><a accesskey="u" href="appendix_porting.html">Up</a></td><td width="40%" align="right">��<a accesskey="n" href="api.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Testing��</td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top">��API Evolution and Deprecation History</td></tr></table></div></body></html>