1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml"><head><title>ABI Policy and Guidelines</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><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="Test"/><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 align="left"><a accesskey="p" href="test.html">Prev</a> </td><th width="60%" align="center">Appendix B.
4 Porting and Maintenance
6 </th><td align="right"> <a accesskey="n" href="api.html">Next</a></td></tr></table><hr/></div><div class="section" title="ABI Policy and Guidelines"><div class="titlepage"><div><div><h2 class="title"><a id="appendix.porting.abi"/>ABI Policy and Guidelines</h2></div></div></div><p>
7 </p><div class="section" title="The C++ Interface"><div class="titlepage"><div><div><h3 class="title"><a id="abi.cxx_interface"/>The C++ Interface</h3></div></div></div><p>
8 C++ applications often depend on specific language support
9 routines, say for throwing exceptions, or catching exceptions, and
10 perhaps also depend on features in the C++ Standard Library.
12 The C++ Standard Library has many include files, types defined in
13 those include files, specific named functions, and other
14 behavior. The text of these behaviors, as written in source include
15 files, is called the Application Programing Interface, or API.
17 Furthermore, C++ source that is compiled into object files is
18 transformed by the compiler: it arranges objects with specific
19 alignment and in a particular layout, mangling names according to a
20 well-defined algorithm, has specific arrangements for the support of
21 virtual functions, etc. These details are defined as the compiler
22 Application Binary Interface, or ABI. The GNU C++ compiler uses an
23 industry-standard C++ ABI starting with version 3. Details can be
24 found in the <a class="link" href="http://www.codesourcery.com/public/cxx-abi/abi.html">ABI
27 The GNU C++ compiler, g++, has a compiler command line option to
28 switch between various different C++ ABIs. This explicit version
29 switch is the flag <code class="code">-fabi-version</code>. In addition, some
30 g++ command line options may change the ABI as a side-effect of
31 use. Such flags include <code class="code">-fpack-struct</code> and
32 <code class="code">-fno-exceptions</code>, but include others: see the complete
33 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">Options
34 for Code Generation Conventions</a>.
36 The configure options used when building a specific libstdc++
37 version may also impact the resulting library ABI. The available
38 configure options, and their impact on the library ABI, are
40 <a class="link" href="configure.html" title="Configure">here</a>.
41 </p><p> Putting all of these ideas together results in the C++ Standard
42 library ABI, which is the compilation of a given library API by a
43 given compiler ABI. In a nutshell:
45 <span class="quote">“<span class="quote">
46 library API + compiler ABI = library ABI
49 The library ABI is mostly of interest for end-users who have
50 unresolved symbols and are linking dynamically to the C++ Standard
51 library, and who thus must be careful to compile their application
52 with a compiler that is compatible with the available C++ Standard
53 library binary. In this case, compatible is defined with the equation
54 above: given an application compiled with a given compiler ABI and
55 library API, it will work correctly with a Standard C++ Library
56 created with the same constraints.
58 To use a specific version of the C++ ABI, one must use a
59 corresponding GNU C++ toolchain (i.e., g++ and libstdc++) that
60 implements the C++ ABI in question.
61 </p></div><div class="section" title="Versioning"><div class="titlepage"><div><div><h3 class="title"><a id="abi.versioning"/>Versioning</h3></div></div></div><p> The C++ interface has evolved throughout the history of the GNU
62 C++ toolchain. With each release, various details have been changed so
63 as to give distinct versions to the C++ interface.
64 </p><div class="section" title="Goals"><div class="titlepage"><div><div><h4 class="title"><a id="abi.versioning.goals"/>Goals</h4></div></div></div><p>Extending existing, stable ABIs. Versioning gives subsequent
65 releases of library binaries the ability to add new symbols and add
66 functionality, all the while retaining compatibility with the previous
67 releases in the series. Thus, program binaries linked with the initial
68 release of a library binary will still run correctly if the library
69 binary is replaced by carefully-managed subsequent library
70 binaries. This is called forward compatibility.
72 The reverse (backwards compatibility) is not true. It is not possible
73 to take program binaries linked with the latest version of a library
74 binary in a release series (with additional symbols added), substitute
75 in the initial release of the library binary, and remain link
77 </p><p>Allows multiple, incompatible ABIs to coexist at the same time.
78 </p></div><div class="section" title="History"><div class="titlepage"><div><div><h4 class="title"><a id="abi.versioning.history"/>History</h4></div></div></div><p>
79 How can this complexity be managed? What does C++ versioning mean?
80 Because library and compiler changes often make binaries compiled
81 with one version of the GNU tools incompatible with binaries
82 compiled with other (either newer or older) versions of the same GNU
83 tools, specific techniques are used to make managing this complexity
86 The following techniques are used:
87 </p><div class="orderedlist"><ol class="orderedlist"><li class="listitem"><p>Release versioning on the libgcc_s.so binary. </p><p>This is implemented via file names and the ELF
88 <code class="constant">DT_SONAME</code> mechanism (at least on ELF
89 systems). It is versioned as follows:
90 </p><div class="itemizedlist"><ul class="itemizedlist"><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"><li class="listitem"><p>GCC 3.4, GCC 4.x: libgcc_s.so.1
91 when configuring <code class="code">--with-sjlj-exceptions</code>, or
92 libgcc_s.so.2 </p></li></ul></div><p>For hppa-linux the versions differ as follows: </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>GCC 3.4, GCC 4.[0-1]: either libgcc_s.so.1
93 when configuring <code class="code">--with-sjlj-exceptions</code>, or
94 libgcc_s.so.2 </p></li><li class="listitem"><p>GCC 4.[2-7]: either libgcc_s.so.3 when configuring
95 <code class="code">--with-sjlj-exceptions</code>) or libgcc_s.so.4
96 </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
97 definitions, where the version definition is the maximum for a
98 particular release. Labels are cumulative. If a particular release
99 is not listed, it has the same version labels as the preceding
100 release.</p><p>This corresponds to the mapfile: gcc/libgcc-std.ver</p><div class="itemizedlist"><ul class="itemizedlist"><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></ul></div></li><li class="listitem"><p>
101 Release versioning on the libstdc++.so binary, implemented in
102 the same way as the libgcc_s.so binary above. Listed is the
103 filename: <code class="constant">DT_SONAME</code> can be deduced from
104 the filename by removing the last two period-delimited numbers. For
105 example, filename <code class="filename">libstdc++.so.5.0.4</code>
106 corresponds to a <code class="constant">DT_SONAME</code> of
107 <code class="constant">libstdc++.so.5</code>. Binaries with equivalent
108 <code class="constant">DT_SONAME</code>s are forward-compatibile: in
109 the table below, releases incompatible with the previous
110 one are explicitly noted.
111 If a particular release is not listed, its libstdc++.so binary
112 has the same filename and <code class="constant">DT_SONAME</code> as the
114 </p><p>It is versioned as follows:
115 </p><div class="itemizedlist"><ul class="itemizedlist"><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></ul></div><p>
116 Note 1: Error should be libstdc++.so.3.0.3.
118 Note 2: Not strictly required.
120 Note 3: This release (but not previous or subsequent) has one
121 known incompatibility, see <a class="link" href="http://gcc.gnu.org/bugzilla/show_bug.cgi?id=33678">33678</a>
122 in the GCC bug database.
123 </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
124 definitions, where the version definition is the maximum for a
125 particular release. Note, only symbols which are newly introduced
126 will use the maximum version definition. Thus, for release series
127 with the same label, but incremented version definitions, the later
128 release has both versions. (An example of this would be the
129 GCC 3.2.1 release, which has GLIBCPP_3.2.1 for new symbols and
130 GLIBCPP_3.2 for symbols that were introduced in the GCC 3.2.0
131 release.) If a particular release is not listed, it has the same
132 version labels as the preceding release.
133 </p><div class="itemizedlist"><ul class="itemizedlist"><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></ul></div></li><li class="listitem"><p>Incremental bumping of a compiler pre-defined macro,
134 __GXX_ABI_VERSION. This macro is defined as the version of the
135 compiler v3 ABI, with g++ 3.0 being version 100. This macro will
136 be automatically defined whenever g++ is used (the curious can
137 test this by invoking g++ with the '-v' flag.)
139 This macro was defined in the file "lang-specs.h" in the gcc/cp directory.
140 Later versions defined it in "c-common.c" in the gcc directory, and from
141 G++ 3.4 it is defined in c-cppbuiltin.c and its value determined by the
142 '-fabi-version' command line option.
144 It is versioned as follows, where 'n' is given by '-fabi-version=n':
145 </p><div class="itemizedlist"><ul class="itemizedlist"><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/></li><li class="listitem"><p>Changes to the default compiler option for
146 <code class="code">-fabi-version</code>.
148 It is versioned as follows:
149 </p><div class="itemizedlist"><ul class="itemizedlist"><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></ul></div><p/></li><li class="listitem"><p>Incremental bumping of a library pre-defined macro. For releases
150 before 3.4.0, the macro is __GLIBCPP__. For later releases, it's
151 __GLIBCXX__. (The libstdc++ project generously changed from CPP to
152 CXX throughout its source to allow the "C" pre-processor the CPP
153 macro namespace.) These macros are defined as the date the library
154 was released, in compressed ISO date format, as an unsigned long.
156 This macro is defined in the file "c++config" in the
157 "libstdc++-v3/include/bits" directory. (Up to GCC 4.1.0, it was
158 changed every night by an automated script. Since GCC 4.1.0, it is
159 the same value as gcc/DATESTAMP.)
161 It is versioned as follows:
162 </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>GCC 3.0.0: 20010615</p></li><li class="listitem"><p>GCC 3.0.1: 20010819</p></li><li class="listitem"><p>GCC 3.0.2: 20011023</p></li><li class="listitem"><p>GCC 3.0.3: 20011220</p></li><li class="listitem"><p>GCC 3.0.4: 20020220</p></li><li class="listitem"><p>GCC 3.1.0: 20020514</p></li><li class="listitem"><p>GCC 3.1.1: 20020725</p></li><li class="listitem"><p>GCC 3.2.0: 20020814</p></li><li class="listitem"><p>GCC 3.2.1: 20021119</p></li><li class="listitem"><p>GCC 3.2.2: 20030205</p></li><li class="listitem"><p>GCC 3.2.3: 20030422</p></li><li class="listitem"><p>GCC 3.3.0: 20030513</p></li><li class="listitem"><p>GCC 3.3.1: 20030804</p></li><li class="listitem"><p>GCC 3.3.2: 20031016</p></li><li class="listitem"><p>GCC 3.3.3: 20040214</p></li><li class="listitem"><p>GCC 3.4.0: 20040419</p></li><li class="listitem"><p>GCC 3.4.1: 20040701</p></li><li class="listitem"><p>GCC 3.4.2: 20040906</p></li><li class="listitem"><p>GCC 3.4.3: 20041105</p></li><li class="listitem"><p>GCC 3.4.4: 20050519</p></li><li class="listitem"><p>GCC 3.4.5: 20051201</p></li><li class="listitem"><p>GCC 3.4.6: 20060306</p></li><li class="listitem"><p>GCC 4.0.0: 20050421</p></li><li class="listitem"><p>GCC 4.0.1: 20050707</p></li><li class="listitem"><p>GCC 4.0.2: 20050921</p></li><li class="listitem"><p>GCC 4.0.3: 20060309</p></li><li class="listitem"><p>GCC 4.1.0: 20060228</p></li><li class="listitem"><p>GCC 4.1.1: 20060524</p></li><li class="listitem"><p>GCC 4.1.2: 20070214</p></li><li class="listitem"><p>GCC 4.2.0: 20070514</p></li><li class="listitem"><p>GCC 4.2.1: 20070719</p></li><li class="listitem"><p>GCC 4.2.2: 20071007</p></li><li class="listitem"><p>GCC 4.2.3: 20080201</p></li><li class="listitem"><p>GCC 4.2.4: 20080519</p></li><li class="listitem"><p>GCC 4.3.0: 20080306</p></li><li class="listitem"><p>GCC 4.3.1: 20080606</p></li><li class="listitem"><p>GCC 4.3.2: 20080827</p></li><li class="listitem"><p>GCC 4.3.3: 20090124</p></li><li class="listitem"><p>GCC 4.3.4: 20090804</p></li><li class="listitem"><p>GCC 4.3.5: 20100522</p></li><li class="listitem"><p>GCC 4.3.6: 20110627</p></li><li class="listitem"><p>GCC 4.4.0: 20090421</p></li><li class="listitem"><p>GCC 4.4.1: 20090722</p></li><li class="listitem"><p>GCC 4.4.2: 20091015</p></li><li class="listitem"><p>GCC 4.4.3: 20100121</p></li><li class="listitem"><p>GCC 4.4.4: 20100429</p></li><li class="listitem"><p>GCC 4.4.5: 20101001</p></li><li class="listitem"><p>GCC 4.4.6: 20110416</p></li><li class="listitem"><p>GCC 4.5.0: 20100414</p></li><li class="listitem"><p>GCC 4.5.1: 20100731</p></li><li class="listitem"><p>GCC 4.5.2: 20101216</p></li><li class="listitem"><p>GCC 4.5.3: 20110428</p></li><li class="listitem"><p>GCC 4.6.0: 20110325</p></li><li class="listitem"><p>GCC 4.6.1: 20110627</p></li><li class="listitem"><p>GCC 4.6.2: 20111026</p></li></ul></div><p/></li><li class="listitem"><p>
163 Incremental bumping of a library pre-defined macro,
164 _GLIBCPP_VERSION. This macro is defined as the released version of
165 the library, as a string literal. This is only implemented in
166 GCC 3.1.0 releases and higher, and is deprecated in 3.4 (where it
167 is called _GLIBCXX_VERSION).
169 This macro is defined in the file "c++config" in the
170 "libstdc++-v3/include/bits" directory and is generated
171 automatically by autoconf as part of the configure-time generation
174 It is versioned as follows:
175 </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>GCC 3.0.0: "3.0.0"</p></li><li class="listitem"><p>GCC 3.0.1: "3.0.0" (Error, should be "3.0.1")</p></li><li class="listitem"><p>GCC 3.0.2: "3.0.0" (Error, should be "3.0.2")</p></li><li class="listitem"><p>GCC 3.0.3: "3.0.0" (Error, should be "3.0.3")</p></li><li class="listitem"><p>GCC 3.0.4: "3.0.0" (Error, should be "3.0.4")</p></li><li class="listitem"><p>GCC 3.1.0: "3.1.0"</p></li><li class="listitem"><p>GCC 3.1.1: "3.1.1"</p></li><li class="listitem"><p>GCC 3.2.0: "3.2"</p></li><li class="listitem"><p>GCC 3.2.1: "3.2.1"</p></li><li class="listitem"><p>GCC 3.2.2: "3.2.2"</p></li><li class="listitem"><p>GCC 3.2.3: "3.2.3"</p></li><li class="listitem"><p>GCC 3.3.0: "3.3"</p></li><li class="listitem"><p>GCC 3.3.1: "3.3.1"</p></li><li class="listitem"><p>GCC 3.3.2: "3.3.2"</p></li><li class="listitem"><p>GCC 3.3.3: "3.3.3"</p></li><li class="listitem"><p>GCC 3.4: "version-unused"</p></li><li class="listitem"><p>GCC 4.x: "version-unused"</p></li></ul></div><p/></li><li class="listitem"><p>
176 Matching each specific C++ compiler release to a specific set of
177 C++ include files. This is only implemented in GCC 3.1.1 releases
180 All C++ includes are installed in
181 <code class="filename">include/c++</code>, then nest in a
182 directory hierarchy corresponding to the C++ compiler's released
183 version. This version corresponds to the variable "gcc_version" in
184 "libstdc++-v3/acinclude.m4," and more details can be found in that
185 file's macro GLIBCXX_CONFIGURE (GLIBCPP_CONFIGURE before GCC 3.4.0).
187 C++ includes are versioned as follows:
188 </p><div class="itemizedlist"><ul class="itemizedlist"><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></ul></div><p/></li></ol></div><p>
189 Taken together, these techniques can accurately specify interface
190 and implementation changes in the GNU C++ tools themselves. Used
191 properly, they allow both the GNU C++ tools implementation, and
192 programs using them, an evolving yet controlled development that
193 maintains backward compatibility.
194 </p></div><div class="section" title="Prerequisites"><div class="titlepage"><div><div><h4 class="title"><a id="abi.versioning.prereq"/>Prerequisites</h4></div></div></div><p>
195 Minimum environment that supports a versioned ABI: A supported
196 dynamic linker, a GNU linker of sufficient vintage to understand
197 demangled C++ name globbing (ld) or the Sun linker, a shared
199 with g++, and shared libraries (libgcc_s, libstdc++) compiled by
200 a compiler (g++) with a compatible ABI. Phew.
202 On top of all that, an additional constraint: libstdc++ did not
203 attempt to version symbols (or age gracefully, really) until
206 Most modern GNU/Linux and BSD versions, particularly ones using
207 GCC 3.1 and later, will meet the
208 requirements above, as does Solaris 2.5 and up.
209 </p></div><div class="section" title="Configuring"><div class="titlepage"><div><div><h4 class="title"><a id="abi.versioning.config"/>Configuring</h4></div></div></div><p>
210 It turns out that most of the configure options that change
211 default behavior will impact the mangled names of exported
212 symbols, and thus impact versioning and compatibility.
214 For more information on configure options, including ABI
216 <a class="link" href="configure.html" title="Configure">here</a>
218 There is one flag that explicitly deals with symbol versioning:
221 In particular, libstdc++-v3/acinclude.m4 has a macro called
222 GLIBCXX_ENABLE_SYMVERS that defaults to yes (or the argument
223 passed in via --enable-symvers=foo). At that point, the macro
224 attempts to make sure that all the requirement for symbol
225 versioning are in place. For more information, please consult
227 </p></div><div class="section" title="Checking Active"><div class="titlepage"><div><div><h4 class="title"><a id="abi.versioning.active"/>Checking Active</h4></div></div></div><p>
228 When the GNU C++ library is being built with symbol versioning
229 on, you should see the following at configure time for
231 </p><pre class="screen">
232 <code class="computeroutput">
233 checking versioning on shared library symbols... gnu
236 or another of the supported styles.
237 If you don't see this line in the configure output, or if this line
238 appears but the last word is 'no', then you are out of luck.
240 If the compiler is pre-installed, a quick way to test is to compile
241 the following (or any) simple C++ file and link it to the shared
243 </p><pre class="programlisting">
244 #include <iostream>
247 { std::cout << "hello" << std::endl; return 0; }
249 %g++ hello.cc -o hello.out
252 libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0x00764000)
253 libm.so.6 => /lib/tls/libm.so.6 (0x004a8000)
254 libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40016000)
255 libc.so.6 => /lib/tls/libc.so.6 (0x0036d000)
256 /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000)
260 If you see symbols in the resulting output with "GLIBCXX_3" as part
261 of the name, then the executable is versioned. Here's an example:
263 <code class="code">U _ZNSt8ios_base4InitC1Ev@@GLIBCXX_3.4</code>
265 On Solaris 2, you can use <code class="code">pvs -r</code> instead:
266 </p><pre class="programlisting">
267 %g++ hello.cc -o hello.out
270 libstdc++.so.6 (GLIBCXX_3.4, GLIBCXX_3.4.12);
271 libgcc_s.so.1 (GCC_3.0);
272 libc.so.1 (SUNWprivate_1.1, SYSVABI_1.3);
274 <code class="code">ldd -v</code> works too, but is very verbose.
275 </p></div></div><div class="section" title="Allowed Changes"><div class="titlepage"><div><div><h3 class="title"><a id="abi.changes_allowed"/>Allowed Changes</h3></div></div></div><p>
276 The following will cause the library minor version number to
277 increase, say from "libstdc++.so.3.0.4" to "libstdc++.so.3.0.5".
278 </p><div class="orderedlist"><ol class="orderedlist"><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>
279 Other allowed changes are possible.
280 </p></div><div class="section" title="Prohibited Changes"><div class="titlepage"><div><div><h3 class="title"><a id="abi.changes_no"/>Prohibited Changes</h3></div></div></div><p>
281 The following non-exhaustive list will cause the library major version
282 number to increase, say from "libstdc++.so.3.0.4" to
283 "libstdc++.so.4.0.0".
284 </p><div class="orderedlist"><ol class="orderedlist"><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
285 base classes</p></li><li class="listitem"><p>
286 Changing the size, alignment, or layout of types
287 specified in the C++ standard. These may not necessarily be
288 instantiated or otherwise exported in the library binary, and
289 include all the required locale facets, as well as things like
290 std::basic_streambuf, et al.
291 </p></li><li class="listitem"><p> Adding an explicit copy constructor or destructor to a
292 class that would otherwise have implicit versions. This will change
293 the way the compiler deals with this class in by-value return
294 statements or parameters: instead of passing instances of this
295 class in registers, the compiler will be forced to use memory. See the
296 section on <a class="link" href="http://www.codesourcery.com/public/cxx-abi/abi.html#calls">Function
297 Calling Conventions and APIs</a>
298 of the C++ ABI documentation for further details.
299 </p></li></ol></div></div><div class="section" title="Implementation"><div class="titlepage"><div><div><h3 class="title"><a id="abi.impl"/>Implementation</h3></div></div></div><div class="orderedlist"><ol class="orderedlist"><li class="listitem"><p>
300 Separation of interface and implementation
302 This is accomplished by two techniques that separate the API from
303 the ABI: forcing undefined references to link against a library
304 binary for definitions.
305 </p><div class="variablelist"><dl><dt><span class="term">Include files have declarations, source files have defines</span></dt><dd><p>
306 For non-templatized types, such as much of <code class="code">class
307 locale</code>, the appropriate standard C++ include, say
308 <code class="code">locale</code>, can contain full declarations, while
309 various source files (say <code class="code"> locale.cc, locale_init.cc,
310 localename.cc</code>) contain definitions.
311 </p></dd><dt><span class="term">Extern template on required types</span></dt><dd><p>
312 For parts of the standard that have an explicit list of
313 required instantiations, the GNU extension syntax <code class="code"> extern
314 template </code> can be used to control where template
315 definitions reside. By marking required instantiations as
316 <code class="code"> extern template </code> in include files, and providing
317 explicit instantiations in the appropriate instantiation files,
318 non-inlined template functions can be versioned. This technique
319 is mostly used on parts of the standard that require <code class="code">
320 char</code> and <code class="code"> wchar_t</code> instantiations, and
321 includes <code class="code"> basic_string</code>, the locale facets, and the
322 types in <code class="code"> iostreams</code>.
323 </p></dd></dl></div><p>
324 In addition, these techniques have the additional benefit that they
325 reduce binary size, which can increase runtime performance.
326 </p></li><li class="listitem"><p>
327 Namespaces linking symbol definitions to export mapfiles
329 All symbols in the shared library binary are processed by a
330 linker script at build time that either allows or disallows
331 external linkage. Because of this, some symbols, regardless of
332 normal C/C++ linkage, are not visible. Symbols that are internal
333 have several appealing characteristics: by not exporting the
334 symbols, there are no relocations when the shared library is
335 started and thus this makes for faster runtime loading
336 performance by the underlying dynamic loading mechanism. In
337 addition, they have the possibility of changing without impacting
339 </p><p>The following namespaces are transformed by the mapfile:</p><div class="variablelist"><dl><dt><span class="term"><code class="code">namespace std</code></span></dt><dd><p> Defaults to exporting all symbols in label
340 <code class="code">GLIBCXX</code> that do not begin with an underscore, i.e.,
341 <code class="code">__test_func</code> would not be exported by default. Select
342 exceptional 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
343 <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
344 <code class="code">CXXABI</code>, select items are allowed to be visible.</p></dd></dl></div><p>
345 </p></li><li class="listitem"><p>Freezing the API</p><p>Disallowed changes, as above, are not made on a stable release
346 branch. Enforcement tends to be less strict with GNU extensions that
347 standard includes.</p></li></ol></div></div><div class="section" title="Testing"><div class="titlepage"><div><div><h3 class="title"><a id="abi.testing"/>Testing</h3></div></div></div><div class="section" title="Single ABI Testing"><div class="titlepage"><div><div><h4 class="title"><a id="abi.testing.single"/>Single ABI Testing</h4></div></div></div><p>
348 Testing for GNU C++ ABI changes is composed of two distinct
349 areas: testing the C++ compiler (g++) for compiler changes, and
350 testing the C++ library (libstdc++) for library changes.
352 Testing the C++ compiler ABI can be done various ways.
354 One. Intel ABI checker.
357 The second is yet unreleased, but has been announced on the gcc
358 mailing list. It is yet unspecified if these tools will be freely
359 available, and able to be included in a GNU project. Please contact
360 Mark Mitchell (mark@codesourcery.com) for more details, and current
364 Involves using the vlad.consistency test framework. This has also been
365 discussed on the gcc mailing lists.
367 Testing the C++ library ABI can also be done various ways.
370 (Brendan Kehoe, Jeff Law suggestion to run 'make check-c++' two ways,
371 one with a new compiler and an old library, and the other with an old
372 compiler and a new library, and look for testsuite regressions)
374 Details on how to set this kind of test up can be found here:
375 http://gcc.gnu.org/ml/gcc/2002-08/msg00142.html
378 Use the 'make check-abi' rule in the libstdc++ Makefile.
380 This is a proactive check of the library ABI. Currently, exported symbol
381 names that are either weak or defined are checked against a last known
382 good baseline. Currently, this baseline is keyed off of 3.4.0
383 binaries, as this was the last time the .so number was incremented. In
384 addition, all exported names are demangled, and the exported objects
385 are checked to make sure they are the same size as the same object in
388 Notice that each baseline is relative to a <span class="emphasis"><em>default</em></span>
389 configured library and compiler: in particular, if options such as
390 --enable-clocale, or --with-cpu, in case of multilibs, are used at
391 configure time, the check may fail, either because of substantive
392 differences or because of limitations of the current checking
395 This dataset is insufficient, yet a start. Also needed is a
396 comprehensive check for all user-visible types part of the standard
397 library for sizeof() and alignof() changes.
399 Verifying compatible layouts of objects is not even attempted. It
400 should be possible to use sizeof, alignof, and offsetof to compute
401 offsets for each structure and type in the standard library, saving to
402 another datafile. Then, compute this in a similar way for new
403 binaries, and look for differences.
405 Another approach might be to use the -fdump-class-hierarchy flag to
406 get information. However, currently this approach gives insufficient
407 data for use in library testing, as class data members, their offsets,
408 and other detailed data is not displayed with this flag.
409 (See PR g++/7470 on how this was used to find bugs.)
411 Perhaps there are other C++ ABI checkers. If so, please notify
412 us. We'd like to know about them!
413 </p></div><div class="section" title="Multiple ABI Testing"><div class="titlepage"><div><div><h4 class="title"><a id="abi.testing.multi"/>Multiple ABI Testing</h4></div></div></div><p>
414 A "C" application, dynamically linked to two shared libraries, liba,
415 libb. The dependent library liba is a C++ shared library compiled with
416 GCC 3.3, and uses io, exceptions, locale, etc. The dependent library
417 libb is a C++ shared library compiled with GCC 3.4, and also uses io,
418 exceptions, locale, etc.
419 </p><p> As above, libone is constructed as follows: </p><pre class="programlisting">
420 %$bld/H-x86-gcc-3.4.0/bin/g++ -fPIC -DPIC -c a.cc
422 %$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
424 %ln -s libone.so.1.0.0 libone.so
426 %$bld/H-x86-gcc-3.4.0/bin/g++ -c a.cc
429 </pre><p> And, libtwo is constructed as follows: </p><pre class="programlisting">
430 %$bld/H-x86-gcc-3.3.3/bin/g++ -fPIC -DPIC -c b.cc
432 %$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
434 %ln -s libtwo.so.1.0.0 libtwo.so
436 %$bld/H-x86-gcc-3.3.3/bin/g++ -c b.cc
439 </pre><p> ...with the resulting libraries looking like </p><pre class="screen">
440 <code class="computeroutput">
442 libstdc++.so.6 => /usr/lib/libstdc++.so.6 (0x40016000)
443 libm.so.6 => /lib/tls/libm.so.6 (0x400fa000)
444 libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x4011c000)
445 libc.so.6 => /lib/tls/libc.so.6 (0x40125000)
446 /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000)
449 libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0x40027000)
450 libm.so.6 => /lib/tls/libm.so.6 (0x400e1000)
451 libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40103000)
452 libc.so.6 => /lib/tls/libc.so.6 (0x4010c000)
453 /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000)
456 Then, the "C" compiler is used to compile a source file that uses
457 functions from each library.
458 </p><pre class="programlisting">
459 gcc test.c -g -O2 -L. -lone -ltwo /usr/lib/libstdc++.so.5 /usr/lib/libstdc++.so.6
461 Which gives the expected:
462 </p><pre class="screen">
463 <code class="computeroutput">
465 libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0x00764000)
466 libstdc++.so.6 => /usr/lib/libstdc++.so.6 (0x40015000)
467 libc.so.6 => /lib/tls/libc.so.6 (0x0036d000)
468 libm.so.6 => /lib/tls/libm.so.6 (0x004a8000)
469 libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x400e5000)
470 /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000)
473 This resulting binary, when executed, will be able to safely use
474 code from both liba, and the dependent libstdc++.so.6, and libb,
475 with the dependent libstdc++.so.5.
476 </p></div></div><div class="section" title="Outstanding Issues"><div class="titlepage"><div><div><h3 class="title"><a id="abi.issues"/>Outstanding Issues</h3></div></div></div><p>
477 Some features in the C++ language make versioning especially
478 difficult. In particular, compiler generated constructs such as
479 implicit instantiations for templates, typeinfo information, and
480 virtual tables all may cause ABI leakage across shared library
481 boundaries. Because of this, mixing C++ ABIs is not recommended at
484 For more background on this issue, see these bugzilla entries:
486 <a class="link" href="http://gcc.gnu.org/PR24660">24660: versioning weak symbols in libstdc++</a>
488 <a class="link" href="http://gcc.gnu.org/PR19664">19664: libstdc++ headers should have pop/push of the visibility around the declarations</a>
489 </p></div><div class="bibliography" title="Bibliography"><div class="titlepage"><div><div><h3 class="title"><a id="abi.biblio"/>Bibliography</h3></div></div></div><div class="biblioentry" title="ABIcheck"><a id="biblio.abicheck"/><p>[biblio.abicheck] <span class="title"><em>
490 <a class="link" href="http://abicheck.sourceforge.net">
493 </em>. </span></p></div><div class="biblioentry" title="C++ ABI Summary"><a id="biblio.cxxabi"/><p>[biblio.cxxabi] <span class="title"><em>
494 <a class="link" href="http://www.codesourcery.com/public/cxx-abi">
497 </em>. </span></p></div><div class="biblioentry" title="Intel Compilers for Linux Compatibility with the GNU Compilers"><a id="id560115"/><p><span class="title"><em>
498 <a class="link" href="http://www.intel.com/cd/software/products/asmo-na/eng/284736.htm">
499 Intel Compilers for Linux Compatibility with the GNU Compilers
501 </em>. </span></p></div><div class="biblioentry" title="Linker and Libraries Guide (document 819-0690)"><a id="id560131"/><p><span class="title"><em>
502 <a class="link" href="http://download.oracle.com/docs/cd/E19963-01/html/819-0690/index.html">
503 Linker and Libraries Guide (document 819-0690)
505 </em>. </span></p></div><div class="biblioentry" title="Sun Studio 11: C++ Migration Guide (document 819-3689)"><a id="id560146"/><p><span class="title"><em>
506 <a class="link" href="http://download.oracle.com/docs/cd/E19422-01/819-3689/index.html">
507 Sun Studio 11: C++ Migration Guide (document 819-3689)
509 </em>. </span></p></div><div class="biblioentry" title="How to Write Shared Libraries"><a id="id560162"/><p><span class="title"><em>
510 <a class="link" href="http://www.akkadia.org/drepper/dsohowto.pdf">
511 How to Write Shared Libraries
513 </em>. </span><span class="author"><span class="firstname">Ulrich</span> <span class="surname">Drepper</span>. </span></p></div><div class="biblioentry" title="C++ ABI for the ARM Architecture"><a id="id560190"/><p><span class="title"><em>
514 <a class="link" href="http://www.arm.com/miscPDFs/8033.pdf">
515 C++ ABI for the ARM Architecture
517 </em>. </span></p></div><div class="biblioentry" title="Dynamic Shared Objects: Survey and Issues"><a id="id560205"/><p><span class="title"><em>
518 <a class="link" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1976.html">
519 Dynamic Shared Objects: Survey and Issues
521 </em>. </span><span class="subtitle">
523 . </span><span class="author"><span class="firstname">Benjamin</span> <span class="surname">Kosnik</span>. </span></p></div><div class="biblioentry" title="Versioning With Namespaces"><a id="id560233"/><p><span class="title"><em>
524 <a class="link" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n2013.html">
525 Versioning With Namespaces
527 </em>. </span><span class="subtitle">
529 . </span><span class="author"><span class="firstname">Benjamin</span> <span class="surname">Kosnik</span>. </span></p></div><div class="biblioentry" title="Binary Compatibility of Shared Libraries Implemented in C++ on GNU/Linux Systems"><a id="id560260"/><p><span class="title"><em>
530 <a class="link" href="http://syrcose.ispras.ru/2009/files/SYRCoSE2009-CfP.pdf">
531 Binary Compatibility of Shared Libraries Implemented in C++
534 </em>. </span><span class="subtitle">
536 . </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 align="left"><a accesskey="p" href="test.html">Prev</a> </td><td align="center"><a accesskey="u" href="appendix_porting.html">Up</a></td><td align="right"> <a accesskey="n" href="api.html">Next</a></td></tr><tr><td align="left" valign="top">Test </td><td align="center"><a accesskey="h" href="../index.html">Home</a></td><td align="right" valign="top"> API Evolution and Deprecation History</td></tr></table></div></body></html>