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">
3 <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 V1.74.0" /><meta name="keywords" content=" C++ , ABI , version , dynamic , shared " /><meta name="keywords" content=" ISO C++ , library " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="appendix_porting.html" title="Appendix B. Porting and Maintenance" /><link rel="prev" href="internals.html" title="Porting to New Hardware or Operating Systems" /><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="internals.html">Prev</a> </td><th width="60%" align="center">Appendix B. Porting and Maintenance</th><td width="20%" align="right"> <a accesskey="n" href="api.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><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>
4 </p><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="abi.cxx_interface"></a>The C++ Interface</h3></div></div></div><p>
5 C++ applications often dependent on specific language support
6 routines, say for throwing exceptions, or catching exceptions, and
7 perhaps also dependent on features in the C++ Standard Library.
9 The C++ Standard Library has many include files, types defined in
10 those include files, specific named functions, and other
11 behavior. The text of these behaviors, as written in source include
12 files, is called the Application Programing Interface, or API.
14 Furthermore, C++ source that is compiled into object files is
15 transformed by the compiler: it arranges objects with specific
16 alignment and in a particular layout, mangling names according to a
17 well-defined algorithm, has specific arrangements for the support of
18 virtual functions, etc. These details are defined as the compiler
19 Application Binary Interface, or ABI. The GNU C++ compiler uses an
20 industry-standard C++ ABI starting with version 3. Details can be
21 found in the <a class="ulink" href="http://www.codesourcery.com/cxx-abi/abi.html" target="_top"> ABI
24 The GNU C++ compiler, g++, has a compiler command line option to
25 switch between various different C++ ABIs. This explicit version
26 switch is the flag <code class="code">-fabi-version</code>. In addition, some
27 g++ command line options may change the ABI as a side-effect of
28 use. Such flags include <code class="code">-fpack-struct</code> and
29 <code class="code">-fno-exceptions</code>, but include others: see the complete
30 list in the GCC manual under the heading <a class="ulink" href="http://gcc.gnu.org/onlinedocs/gcc/Code-Gen-Options.html#Code%20Gen%20Options" target="_top">Options
31 for Code Generation Conventions</a>.
33 The configure options used when building a specific libstdc++
34 version may also impact the resulting library ABI. The available
35 configure options, and their impact on the library ABI, are
37 <a class="link" href="configure.html" title="Configure">here</a>.
38 </p><p> Putting all of these ideas together results in the C++ Standard
39 library ABI, which is the compilation of a given library API by a
40 given compiler ABI. In a nutshell:
43 library API + compiler ABI = library ABI
46 The library ABI is mostly of interest for end-users who have
47 unresolved symbols and are linking dynamically to the C++ Standard
48 library, and who thus must be careful to compile their application
49 with a compiler that is compatible with the available C++ Standard
50 library binary. In this case, compatible is defined with the equation
51 above: given an application compiled with a given compiler ABI and
52 library API, it will work correctly with a Standard C++ Library
53 created with the same constraints.
55 To use a specific version of the C++ ABI, one must use a
56 corresponding GNU C++ toolchain (i.e., g++ and libstdc++) that
57 implements the C++ ABI in question.
58 </p></div><div class="sect2" lang="en" xml:lang="en"><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
59 C++ toolchain. With each release, various details have been changed so
60 as to give distinct versions to the C++ interface.
61 </p><div class="sect3" lang="en" xml:lang="en"><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
62 releases of library binaries the ability to add new symbols and add
63 functionality, all the while retaining compatibility with the previous
64 releases in the series. Thus, program binaries linked with the initial
65 release of a library binary will still link correctly if the library
66 binary is replaced by carefully-managed subsequent library
67 binaries. This is called forward compatibility.
69 The reverse (backwards compatibility) is not true. It is not possible
70 to take program binaries linked with the latest version of a library
71 binary in a release series (with additional symbols added), substitute
72 in the initial release of the library binary, and remain link
74 </p><p>Allows multiple, incompatible ABIs to coexist at the same time.
75 </p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="abi.versioning.history"></a>History</h4></div></div></div><p>
76 How can this complexity be managed? What does C++ versioning mean?
77 Because library and compiler changes often make binaries compiled
78 with one version of the GNU tools incompatible with binaries
79 compiled with other (either newer or older) versions of the same GNU
80 tools, specific techniques are used to make managing this complexity
83 The following techniques are used:
84 </p><div class="orderedlist"><ol type="1"><li><p>Release versioning on the libgcc_s.so binary. </p><p>This is implemented via file names and the ELF
85 <code class="constant">DT_SONAME</code> mechanism (at least on ELF
86 systems). It is versioned as follows:
87 </p><div class="itemizedlist"><ul type="disc"><li><p>gcc-3.0.0: libgcc_s.so.1</p></li><li><p>gcc-3.0.1: libgcc_s.so.1</p></li><li><p>gcc-3.0.2: libgcc_s.so.1</p></li><li><p>gcc-3.0.3: libgcc_s.so.1</p></li><li><p>gcc-3.0.4: libgcc_s.so.1</p></li><li><p>gcc-3.1.0: libgcc_s.so.1</p></li><li><p>gcc-3.1.1: libgcc_s.so.1</p></li><li><p>gcc-3.2.0: libgcc_s.so.1</p></li><li><p>gcc-3.2.1: libgcc_s.so.1</p></li><li><p>gcc-3.2.2: libgcc_s.so.1</p></li><li><p>gcc-3.2.3: libgcc_s.so.1</p></li><li><p>gcc-3.3.0: libgcc_s.so.1</p></li><li><p>gcc-3.3.1: libgcc_s.so.1</p></li><li><p>gcc-3.3.2: libgcc_s.so.1</p></li><li><p>gcc-3.3.3: libgcc_s.so.1</p></li><li><p>gcc-3.4.x, gcc-4.[0-3].x: on m68k-linux and
88 hppa-linux this is either libgcc_s.so.1 (when configuring
89 <code class="code">--with-sjlj-exceptions</code>) or libgcc_s.so.2. For all
90 others, this is libgcc_s.so.1. </p></li></ul></div></li><li><p>Symbol versioning on the libgcc_s.so binary.</p><p>It is versioned with the following labels and version
91 definitions, where the version definition is the maximum for a
92 particular release. Labels are cumulative. If a particular release
93 is not listed, it has the same version labels as the preceding
94 release.</p><p>This corresponds to the mapfile: gcc/libgcc-std.ver</p><div class="itemizedlist"><ul type="disc"><li><p>gcc-3.0.0: GCC_3.0</p></li><li><p>gcc-3.3.0: GCC_3.3</p></li><li><p>gcc-3.3.1: GCC_3.3.1</p></li><li><p>gcc-3.3.2: GCC_3.3.2</p></li><li><p>gcc-3.3.4: GCC_3.3.4</p></li><li><p>gcc-3.4.0: GCC_3.4</p></li><li><p>gcc-3.4.2: GCC_3.4.2</p></li><li><p>gcc-3.4.4: GCC_3.4.4</p></li><li><p>gcc-4.0.0: GCC_4.0.0</p></li><li><p>gcc-4.1.0: GCC_4.1.0</p></li><li><p>gcc-4.2.0: GCC_4.2.0</p></li><li><p>gcc-4.3.0: GCC_4.3.0</p></li></ul></div></li><li><p>
95 Release versioning on the libstdc++.so binary, implemented in
96 the same was as the libgcc_s.so binary above. Listed is the
97 filename: <code class="constant">DT_SONAME</code> can be deduced from
98 the filename by removing the last two period-delimited numbers. For
99 example, filename <code class="filename">libstdc++.so.5.0.4</code>
100 corresponds to a <code class="constant">DT_SONAME</code> of
101 <code class="constant">libstdc++.so.5</code>. Binaries with equivalent
102 <code class="constant">DT_SONAME</code>s are forward-compatibile: in
103 the table below, releases incompatible with the previous
104 one are explicitly noted.
105 </p><p>It is versioned as follows:
106 </p><div class="itemizedlist"><ul type="disc"><li><p>gcc-3.0.0: libstdc++.so.3.0.0</p></li><li><p>gcc-3.0.1: libstdc++.so.3.0.1</p></li><li><p>gcc-3.0.2: libstdc++.so.3.0.2</p></li><li><p>gcc-3.0.3: libstdc++.so.3.0.2 (See Note 1)</p></li><li><p>gcc-3.0.4: libstdc++.so.3.0.4</p></li><li><p>gcc-3.1.0: libstdc++.so.4.0.0 <span class="emphasis"><em>(Incompatible with previous)</em></span></p></li><li><p>gcc-3.1.1: libstdc++.so.4.0.1</p></li><li><p>gcc-3.2.0: libstdc++.so.5.0.0 <span class="emphasis"><em>(Incompatible with previous)</em></span></p></li><li><p>gcc-3.2.1: libstdc++.so.5.0.1</p></li><li><p>gcc-3.2.2: libstdc++.so.5.0.2</p></li><li><p>gcc-3.2.3: libstdc++.so.5.0.3 (See Note 2)</p></li><li><p>gcc-3.3.0: libstdc++.so.5.0.4</p></li><li><p>gcc-3.3.1: libstdc++.so.5.0.5</p></li><li><p>gcc-3.3.2: libstdc++.so.5.0.5</p></li><li><p>gcc-3.3.3: libstdc++.so.5.0.5</p></li><li><p>gcc-3.4.0: libstdc++.so.6.0.0 <span class="emphasis"><em>(Incompatible with previous)</em></span></p></li><li><p>gcc-3.4.1: libstdc++.so.6.0.1</p></li><li><p>gcc-3.4.2: libstdc++.so.6.0.2</p></li><li><p>gcc-3.4.3: libstdc++.so.6.0.3</p></li><li><p>gcc-3.4.4: libstdc++.so.6.0.3</p></li><li><p>gcc-3.4.5: libstdc++.so.6.0.3</p></li><li><p>gcc-3.4.6: libstdc++.so.6.0.3</p></li><li><p>gcc-4.0.0: libstdc++.so.6.0.4</p></li><li><p>gcc-4.0.1: libstdc++.so.6.0.5</p></li><li><p>gcc-4.0.2: libstdc++.so.6.0.6</p></li><li><p>gcc-4.0.3: libstdc++.so.6.0.7</p></li><li><p>gcc-4.1.0: libstdc++.so.6.0.7</p></li><li><p>gcc-4.1.1: libstdc++.so.6.0.8</p></li><li><p>gcc-4.1.2: libstdc++.so.6.0.8</p></li><li><p>gcc-4.2.0: libstdc++.so.6.0.9</p></li><li><p>gcc-4.2.1: libstdc++.so.6.0.9 (See Note 3)</p></li><li><p>gcc-4.2.2: libstdc++.so.6.0.9</p></li><li><p>gcc-4.2.3: libstdc++.so.6.0.9</p></li><li><p>gcc-4.2.4: libstdc++.so.6.0.9</p></li><li><p>gcc-4.3.0: libstdc++.so.6.0.10</p></li><li><p>gcc-4.3.1: libstdc++.so.6.0.10</p></li><li><p>gcc-4.3.2: libstdc++.so.6.0.10</p></li></ul></div><p>
107 Note 1: Error should be libstdc++.so.3.0.3.
109 Note 2: Not strictly required.
111 Note 3: This release (but not previous or subsequent) has one
112 known incompatibility, see <a class="ulink" href="http://gcc.gnu.org/bugzilla/show_bug.cgi?id=33678" target="_top">33678</a>
113 in the GCC bug database.
114 </p></li><li><p>Symbol versioning on the libstdc++.so binary.</p><p>mapfile: libstdc++/config/linker-map.gnu</p><p>It is versioned with the following labels and version
115 definitions, where the version definition is the maximum for a
116 particular release. Note, only symbol which are newly introduced
117 will use the maximum version definition. Thus, for release series
118 with the same label, but incremented version definitions, the later
119 release has both versions. (An example of this would be the
120 gcc-3.2.1 release, which has GLIBCPP_3.2.1 for new symbols and
121 GLIBCPP_3.2 for symbols that were introduced in the gcc-3.2.0
122 release.) If a particular release is not listed, it has the same
123 version labels as the preceding release.
124 </p><div class="itemizedlist"><ul type="disc"><li><p>gcc-3.0.0: (Error, not versioned)</p></li><li><p>gcc-3.0.1: (Error, not versioned)</p></li><li><p>gcc-3.0.2: (Error, not versioned)</p></li><li><p>gcc-3.0.3: (Error, not versioned)</p></li><li><p>gcc-3.0.4: (Error, not versioned)</p></li><li><p>gcc-3.1.0: GLIBCPP_3.1, CXXABI_1</p></li><li><p>gcc-3.1.1: GLIBCPP_3.1, CXXABI_1</p></li><li><p>gcc-3.2.0: GLIBCPP_3.2, CXXABI_1.2</p></li><li><p>gcc-3.2.1: GLIBCPP_3.2.1, CXXABI_1.2</p></li><li><p>gcc-3.2.2: GLIBCPP_3.2.2, CXXABI_1.2</p></li><li><p>gcc-3.2.3: GLIBCPP_3.2.2, CXXABI_1.2</p></li><li><p>gcc-3.3.0: GLIBCPP_3.2.2, CXXABI_1.2.1</p></li><li><p>gcc-3.3.1: GLIBCPP_3.2.3, CXXABI_1.2.1</p></li><li><p>gcc-3.3.2: GLIBCPP_3.2.3, CXXABI_1.2.1</p></li><li><p>gcc-3.3.3: GLIBCPP_3.2.3, CXXABI_1.2.1</p></li><li><p>gcc-3.4.0: GLIBCXX_3.4, CXXABI_1.3</p></li><li><p>gcc-3.4.1: GLIBCXX_3.4.1, CXXABI_1.3</p></li><li><p>gcc-3.4.2: GLIBCXX_3.4.2</p></li><li><p>gcc-3.4.3: GLIBCXX_3.4.3</p></li><li><p>gcc-4.0.0: GLIBCXX_3.4.4, CXXABI_1.3.1</p></li><li><p>gcc-4.0.1: GLIBCXX_3.4.5</p></li><li><p>gcc-4.0.2: GLIBCXX_3.4.6</p></li><li><p>gcc-4.0.3: GLIBCXX_3.4.7</p></li><li><p>gcc-4.1.1: GLIBCXX_3.4.8</p></li><li><p>gcc-4.2.0: GLIBCXX_3.4.9</p></li><li><p>gcc-4.3.0: GLIBCXX_3.4.10, CXXABI_1.3.2</p></li></ul></div></li><li><p>Incremental bumping of a compiler pre-defined macro,
125 __GXX_ABI_VERSION. This macro is defined as the version of the
126 compiler v3 ABI, with g++ 3.0.x being version 100. This macro will
127 be automatically defined whenever g++ is used (the curious can
128 test this by invoking g++ with the '-v' flag.)
130 This macro was defined in the file "lang-specs.h" in the gcc/cp directory.
131 Later versions defined it in "c-common.c" in the gcc directory, and from
132 G++ 3.4 it is defined in c-cppbuiltin.c and its value determined by the
133 '-fabi-version' command line option.
135 It is versioned as follows, where 'n' is given by '-fabi-version=n':
136 </p><div class="itemizedlist"><ul type="disc"><li><p>gcc-3.0.x: 100</p></li><li><p>gcc-3.1.x: 100 (Error, should be 101)</p></li><li><p>gcc-3.2.x: 102</p></li><li><p>gcc-3.3.x: 102</p></li><li><p>gcc-3.4.x, gcc-4.[0-3].x: 102 (when n=1)</p></li><li><p>gcc-3.4.x, gcc-4.[0-3].x: 1000 + n (when n>1) </p></li><li><p>gcc-3.4.x, gcc-4.[0-3].x: 999999 (when n=0)</p></li></ul></div><p></p></li><li><p>Changes to the default compiler option for
137 <code class="code">-fabi-version</code>.
139 It is versioned as follows:
140 </p><div class="itemizedlist"><ul type="disc"><li><p>gcc-3.0.x: (Error, not versioned) </p></li><li><p>gcc-3.1.x: (Error, not versioned) </p></li><li><p>gcc-3.2.x: <code class="code">-fabi-version=1</code></p></li><li><p>gcc-3.3.x: <code class="code">-fabi-version=1</code></p></li><li><p>gcc-3.4.x, gcc-4.[0-3].x: <code class="code">-fabi-version=2</code> <span class="emphasis"><em>(Incompatible with previous)</em></span></p></li></ul></div><p></p></li><li><p>Incremental bumping of a library pre-defined macro. For releases
141 before 3.4.0, the macro is __GLIBCPP__. For later releases, it's
142 __GLIBCXX__. (The libstdc++ project generously changed from CPP to
143 CXX throughout its source to allow the "C" pre-processor the CPP
144 macro namespace.) These macros are defined as the date the library
145 was released, in compressed ISO date format, as an unsigned long.
147 This macro is defined in the file "c++config" in the
148 "libstdc++/include/bits" directory. (Up to gcc-4.1.0, it was
149 changed every night by an automated script. Since gcc-4.1.0, it is
150 the same value as gcc/DATESTAMP.)
152 It is versioned as follows:
153 </p><div class="itemizedlist"><ul type="disc"><li><p>gcc-3.0.0: 20010615</p></li><li><p>gcc-3.0.1: 20010819</p></li><li><p>gcc-3.0.2: 20011023</p></li><li><p>gcc-3.0.3: 20011220</p></li><li><p>gcc-3.0.4: 20020220</p></li><li><p>gcc-3.1.0: 20020514</p></li><li><p>gcc-3.1.1: 20020725</p></li><li><p>gcc-3.2.0: 20020814</p></li><li><p>gcc-3.2.1: 20021119</p></li><li><p>gcc-3.2.2: 20030205</p></li><li><p>gcc-3.2.3: 20030422</p></li><li><p>gcc-3.3.0: 20030513</p></li><li><p>gcc-3.3.1: 20030804</p></li><li><p>gcc-3.3.2: 20031016</p></li><li><p>gcc-3.3.3: 20040214</p></li><li><p>gcc-3.4.0: 20040419</p></li><li><p>gcc-3.4.1: 20040701</p></li><li><p>gcc-3.4.2: 20040906</p></li><li><p>gcc-3.4.3: 20041105</p></li><li><p>gcc-3.4.4: 20050519</p></li><li><p>gcc-3.4.5: 20051201</p></li><li><p>gcc-3.4.6: 20060306</p></li><li><p>gcc-4.0.0: 20050421</p></li><li><p>gcc-4.0.1: 20050707</p></li><li><p>gcc-4.0.2: 20050921</p></li><li><p>gcc-4.0.3: 20060309</p></li><li><p>gcc-4.1.0: 20060228</p></li><li><p>gcc-4.1.1: 20060524</p></li><li><p>gcc-4.1.2: 20070214</p></li><li><p>gcc-4.2.0: 20070514</p></li><li><p>gcc-4.2.1: 20070719</p></li><li><p>gcc-4.2.2: 20071007</p></li><li><p>gcc-4.2.3: 20080201</p></li><li><p>gcc-4.2.4: 20080519</p></li><li><p>gcc-4.3.0: 20080306</p></li><li><p>gcc-4.3.1: 20080606</p></li><li><p>gcc-4.3.2: 20080827</p></li></ul></div><p></p></li><li><p>
154 Incremental bumping of a library pre-defined macro,
155 _GLIBCPP_VERSION. This macro is defined as the released version of
156 the library, as a string literal. This is only implemented in
157 gcc-3.1.0 releases and higher, and is deprecated in 3.4 (where it
158 is called _GLIBCXX_VERSION).
160 This macro is defined in the file "c++config" in the
161 "libstdc++/include/bits" directory and is generated
162 automatically by autoconf as part of the configure-time generation
165 It is versioned as follows:
166 </p><div class="itemizedlist"><ul type="disc"><li><p>gcc-3.0.0: "3.0.0"</p></li><li><p>gcc-3.0.1: "3.0.0" (Error, should be "3.0.1")</p></li><li><p>gcc-3.0.2: "3.0.0" (Error, should be "3.0.2")</p></li><li><p>gcc-3.0.3: "3.0.0" (Error, should be "3.0.3")</p></li><li><p>gcc-3.0.4: "3.0.0" (Error, should be "3.0.4")</p></li><li><p>gcc-3.1.0: "3.1.0"</p></li><li><p>gcc-3.1.1: "3.1.1"</p></li><li><p>gcc-3.2.0: "3.2"</p></li><li><p>gcc-3.2.1: "3.2.1"</p></li><li><p>gcc-3.2.2: "3.2.2"</p></li><li><p>gcc-3.2.3: "3.2.3"</p></li><li><p>gcc-3.3.0: "3.3"</p></li><li><p>gcc-3.3.1: "3.3.1"</p></li><li><p>gcc-3.3.2: "3.3.2"</p></li><li><p>gcc-3.3.3: "3.3.3"</p></li><li><p>gcc-3.4.x: "version-unused"</p></li><li><p>gcc-4.[0-3].x: "version-unused"</p></li></ul></div><p></p></li><li><p>
167 Matching each specific C++ compiler release to a specific set of
168 C++ include files. This is only implemented in gcc-3.1.1 releases
171 All C++ includes are installed in include/c++, then nest in a
172 directory hierarchy corresponding to the C++ compiler's released
173 version. This version corresponds to the variable "gcc_version" in
174 "libstdc++/acinclude.m4," and more details can be found in that
175 file's macro GLIBCXX_CONFIGURE (GLIBCPP_CONFIGURE before gcc-3.4.0).
177 C++ includes are versioned as follows:
178 </p><div class="itemizedlist"><ul type="disc"><li><p>gcc-3.0.0: include/g++-v3</p></li><li><p>gcc-3.0.1: include/g++-v3</p></li><li><p>gcc-3.0.2: include/g++-v3</p></li><li><p>gcc-3.0.3: include/g++-v3</p></li><li><p>gcc-3.0.4: include/g++-v3</p></li><li><p>gcc-3.1.0: include/g++-v3</p></li><li><p>gcc-3.1.1: include/c++/3.1.1</p></li><li><p>gcc-3.2.0: include/c++/3.2</p></li><li><p>gcc-3.2.1: include/c++/3.2.1</p></li><li><p>gcc-3.2.2: include/c++/3.2.2</p></li><li><p>gcc-3.2.3: include/c++/3.2.3</p></li><li><p>gcc-3.3.0: include/c++/3.3</p></li><li><p>gcc-3.3.1: include/c++/3.3.1</p></li><li><p>gcc-3.3.2: include/c++/3.3.2</p></li><li><p>gcc-3.3.3: include/c++/3.3.3</p></li><li><p>gcc-3.4.0: include/c++/3.4.0</p></li><li><p>gcc-3.4.1: include/c++/3.4.1</p></li><li><p>gcc-3.4.2: include/c++/3.4.2</p></li><li><p>gcc-3.4.3: include/c++/3.4.3</p></li><li><p>gcc-3.4.4: include/c++/3.4.4</p></li><li><p>gcc-3.4.5: include/c++/3.4.5</p></li><li><p>gcc-3.4.6: include/c++/3.4.6</p></li><li><p>gcc-4.0.0: include/c++/4.0.0</p></li><li><p>gcc-4.0.1: include/c++/4.0.1</p></li><li><p>gcc-4.0.2: include/c++/4.0.2</p></li><li><p>gcc-4.0.3: include/c++/4.0.3</p></li><li><p>gcc-4.1.0: include/c++/4.1.0</p></li><li><p>gcc-4.1.1: include/c++/4.1.1</p></li><li><p>gcc-4.1.2: include/c++/4.1.2</p></li><li><p>gcc-4.2.0: include/c++/4.2.0</p></li><li><p>gcc-4.2.1: include/c++/4.2.1</p></li><li><p>gcc-4.2.2: include/c++/4.2.2</p></li><li><p>gcc-4.2.3: include/c++/4.2.3</p></li><li><p>gcc-4.2.4: include/c++/4.2.4</p></li><li><p>gcc-4.3.0: include/c++/4.3.0</p></li><li><p>gcc-4.3.1: include/c++/4.3.1</p></li><li><p>gcc-4.3.2: include/c++/4.3.2</p></li></ul></div><p></p></li></ol></div><p>
179 Taken together, these techniques can accurately specify interface
180 and implementation changes in the GNU C++ tools themselves. Used
181 properly, they allow both the GNU C++ tools implementation, and
182 programs using them, an evolving yet controlled development that
183 maintains backward compatibility.
184 </p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="abi.versioning.prereq"></a>Prerequisites</h4></div></div></div><p>
185 Minimum environment that supports a versioned ABI: A supported
186 dynamic linker, a GNU linker of sufficient vintage to understand
187 demangled C++ name globbing (ld), a shared executable compiled
188 with g++, and shared libraries (libgcc_s, libstdc++) compiled by
189 a compiler (g++) with a compatible ABI. Phew.
191 On top of all that, an additional constraint: libstdc++ did not
192 attempt to version symbols (or age gracefully, really) until
195 Most modern Linux and BSD versions, particularly ones using
196 gcc-3.1.x tools and more recent vintages, will meet the
198 </p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="abi.versioning.config"></a>Configuring</h4></div></div></div><p>
199 It turns out that most of the configure options that change
200 default behavior will impact the mangled names of exported
201 symbols, and thus impact versioning and compatibility.
203 For more information on configure options, including ABI
205 http://gcc.gnu.org/onlinedocs/libstdc++/configopts.html
207 There is one flag that explicitly deals with symbol versioning:
210 In particular, libstdc++/acinclude.m4 has a macro called
211 GLIBCXX_ENABLE_SYMVERS that defaults to yes (or the argument
212 passed in via --enable-symvers=foo). At that point, the macro
213 attempts to make sure that all the requirement for symbol
214 versioning are in place. For more information, please consult
216 </p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="abi.versioning.active"></a>Checking Active</h4></div></div></div><p>
217 When the GNU C++ library is being built with symbol versioning
218 on, you should see the following at configure time for
220 </p><pre class="screen">
221 <code class="computeroutput">
222 checking versioning on shared library symbols... gnu
225 If you don't see this line in the configure output, or if this line
226 appears but the last word is 'no', then you are out of luck.
228 If the compiler is pre-installed, a quick way to test is to compile
229 the following (or any) simple C++ file and link it to the shared
231 </p><pre class="programlisting">
232 #include <iostream>
235 { std::cout << "hello" << std::endl; return 0; }
237 %g++ hello.cc -o hello.out
240 libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0x00764000)
241 libm.so.6 => /lib/tls/libm.so.6 (0x004a8000)
242 libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40016000)
243 libc.so.6 => /lib/tls/libc.so.6 (0x0036d000)
244 /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000)
248 If you see symbols in the resulting output with "GLIBCXX_3" as part
249 of the name, then the executable is versioned. Here's an example:
251 <code class="code">U _ZNSt8ios_base4InitC1Ev@@GLIBCXX_3.4</code>
252 </p></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="abi.changes_allowed"></a>Allowed Changes</h3></div></div></div><p>
253 The following will cause the library minor version number to
254 increase, say from "libstdc++.so.3.0.4" to "libstdc++.so.3.0.5".
255 </p><div class="orderedlist"><ol type="1"><li><p>Adding an exported global or static data member</p></li><li><p>Adding an exported function, static or non-virtual member function</p></li><li><p>Adding an exported symbol or symbols by additional instantiations</p></li></ol></div><p>
256 Other allowed changes are possible.
257 </p></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="abi.changes_no"></a>Prohibited Changes</h3></div></div></div><p>
258 The following non-exhaustive list will cause the library major version
259 number to increase, say from "libstdc++.so.3.0.4" to
260 "libstdc++.so.4.0.0".
261 </p><div class="orderedlist"><ol type="1"><li><p>Changes in the gcc/g++ compiler ABI</p></li><li><p>Changing size of an exported symbol</p></li><li><p>Changing alignment of an exported symbol</p></li><li><p>Changing the layout of an exported symbol</p></li><li><p>Changing mangling on an exported symbol</p></li><li><p>Deleting an exported symbol</p></li><li><p>Changing the inheritance properties of a type by adding or removing
262 base classes</p></li><li><p>
263 Changing the size, alignment, or layout of types
264 specified in the C++ standard. These may not necessarily be
265 instantiated or otherwise exported in the library binary, and
266 include all the required locale facets, as well as things like
267 std::basic_streambuf, et al.
268 </p></li><li><p> Adding an explicit copy constructor or destructor to a
269 class that would otherwise have implicit versions. This will change
270 the way the compiler deals with this class in by-value return
271 statements or parameters: instead of being passing instances of this
272 class in registers, the compiler will be forced to use memory. See <a class="ulink" href="http://www.codesourcery.com/cxx-abi/abi.html#calls" target="_top"> this part</a>
273 of the C++ ABI documentation for further details.
274 </p></li></ol></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="abi.impl"></a>Implementation</h3></div></div></div><div class="orderedlist"><ol type="1"><li><p>
275 Separation of interface and implementation
277 This is accomplished by two techniques that separate the API from
278 the ABI: forcing undefined references to link against a library
279 binary for definitions.
280 </p><div class="variablelist"><dl><dt><span class="term">Include files have declarations, source files have defines</span></dt><dd><p>
281 For non-templatized types, such as much of <code class="code">class
282 locale</code>, the appropriate standard C++ include, say
283 <code class="code">locale</code>, can contain full declarations, while
284 various source files (say <code class="code"> locale.cc, locale_init.cc,
285 localename.cc</code>) contain definitions.
286 </p></dd><dt><span class="term">Extern template on required types</span></dt><dd><p>
287 For parts of the standard that have an explicit list of
288 required instantiations, the GNU extension syntax <code class="code"> extern
289 template </code> can be used to control where template
290 definitions reside. By marking required instantiations as
291 <code class="code"> extern template </code> in include files, and providing
292 explicit instantiations in the appropriate instantiation files,
293 non-inlined template functions can be versioned. This technique
294 is mostly used on parts of the standard that require <code class="code">
295 char</code> and <code class="code"> wchar_t</code> instantiations, and
296 includes <code class="code"> basic_string</code>, the locale facets, and the
297 types in <code class="code"> iostreams</code>.
298 </p></dd></dl></div><p>
299 In addition, these techniques have the additional benefit that they
300 reduce binary size, which can increase runtime performance.
302 Namespaces linking symbol definitions to export mapfiles
304 All symbols in the shared library binary are processed by a
305 linker script at build time that either allows or disallows
306 external linkage. Because of this, some symbols, regardless of
307 normal C/C++ linkage, are not visible. Symbols that are internal
308 have several appealing characteristics: by not exporting the
309 symbols, there are no relocations when the shared library is
310 started and thus this makes for faster runtime loading
311 performance by the underlying dynamic loading mechanism. In
312 addition, they have the possibility of changing without impacting
314 </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
315 <code class="code">GLIBCXX</code> that do not begin with an underscore, i.e.,
316 <code class="code">__test_func</code> would not be exported by default. Select
317 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
318 <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
319 <code class="code">CXXABI</code>, select items are allowed to be visible.</p></dd></dl></div><p>
320 </p></li><li><p>Freezing the API</p><p>Disallowed changes, as above, are not made on a stable release
321 branch. Enforcement tends to be less strict with GNU extensions that
322 standard includes.</p></li></ol></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="abi.testing"></a>Testing</h3></div></div></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="abi.testing.single"></a>Single ABI Testing</h4></div></div></div><p>
323 Testing for GNU C++ ABI changes is composed of two distinct
324 areas: testing the C++ compiler (g++) for compiler changes, and
325 testing the C++ library (libstdc++) for library changes.
327 Testing the C++ compiler ABI can be done various ways.
329 One. Intel ABI checker. More information can be obtained <a class="ulink" href="http://developer.intel.com/software/products/opensource/" target="_top">here.</a>
332 The second is yet unreleased, but has been announced on the gcc
333 mailing list. It is yet unspecified if these tools will be freely
334 available, and able to be included in a GNU project. Please contact
335 Mark Mitchell (mark@codesourcery.com) for more details, and current
339 Involves using the vlad.consistency test framework. This has also been
340 discussed on the gcc mailing lists.
342 Testing the C++ library ABI can also be done various ways.
345 (Brendan Kehoe, Jeff Law suggestion to run 'make check-c++' two ways,
346 one with a new compiler and an old library, and the other with an old
347 compiler and a new library, and look for testsuite regressions)
349 Details on how to set this kind of test up can be found here:
350 http://gcc.gnu.org/ml/gcc/2002-08/msg00142.html
353 Use the 'make check-abi' rule in the libstdc++ Makefile.
355 This is a proactive check the library ABI. Currently, exported symbol
356 names that are either weak or defined are checked against a last known
357 good baseline. Currently, this baseline is keyed off of 3.4.0
358 binaries, as this was the last time the .so number was incremented. In
359 addition, all exported names are demangled, and the exported objects
360 are checked to make sure they are the same size as the same object in
363 Notice that each baseline is relative to a <span class="emphasis"><em>default</em></span>
364 configured library and compiler: in particular, if options such as
365 --enable-clocale, or --with-cpu, in case of multilibs, are used at
366 configure time, the check may fail, either because of substantive
367 differences or because of limitations of the current checking
370 This dataset is insufficient, yet a start. Also needed is a
371 comprehensive check for all user-visible types part of the standard
372 library for sizeof() and alignof() changes.
374 Verifying compatible layouts of objects is not even attempted. It
375 should be possible to use sizeof, alignof, and offsetof to compute
376 offsets for each structure and type in the standard library, saving to
377 another datafile. Then, compute this in a similar way for new
378 binaries, and look for differences.
380 Another approach might be to use the -fdump-class-hierarchy flag to
381 get information. However, currently this approach gives insufficient
382 data for use in library testing, as class data members, their offsets,
383 and other detailed data is not displayed with this flag.
384 (See g++/7470 on how this was used to find bugs.)
386 Perhaps there are other C++ ABI checkers. If so, please notify
387 us. We'd like to know about them!
388 </p></div><div class="sect3" lang="en" xml:lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="abi.testing.multi"></a>Multiple ABI Testing</h4></div></div></div><p>
389 A "C" application, dynamically linked to two shared libraries, liba,
390 libb. The dependent library liba is C++ shared library compiled with
391 gcc-3.3.x, and uses io, exceptions, locale, etc. The dependent library
392 libb is a C++ shared library compiled with gcc-3.4.x, and also uses io,
393 exceptions, locale, etc.
394 </p><p> As above, libone is constructed as follows: </p><pre class="programlisting">
395 %$bld/H-x86-gcc-3.4.0/bin/g++ -fPIC -DPIC -c a.cc
397 %$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
399 %ln -s libone.so.1.0.0 libone.so
401 %$bld/H-x86-gcc-3.4.0/bin/g++ -c a.cc
404 </pre><p> And, libtwo is constructed as follows: </p><pre class="programlisting">
405 %$bld/H-x86-gcc-3.3.3/bin/g++ -fPIC -DPIC -c b.cc
407 %$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
409 %ln -s libtwo.so.1.0.0 libtwo.so
411 %$bld/H-x86-gcc-3.3.3/bin/g++ -c b.cc
414 </pre><p> ...with the resulting libraries looking like </p><pre class="screen">
415 <code class="computeroutput">
417 libstdc++.so.6 => /usr/lib/libstdc++.so.6 (0x40016000)
418 libm.so.6 => /lib/tls/libm.so.6 (0x400fa000)
419 libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x4011c000)
420 libc.so.6 => /lib/tls/libc.so.6 (0x40125000)
421 /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000)
424 libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0x40027000)
425 libm.so.6 => /lib/tls/libm.so.6 (0x400e1000)
426 libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40103000)
427 libc.so.6 => /lib/tls/libc.so.6 (0x4010c000)
428 /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000)
431 Then, the "C" compiler is used to compile a source file that uses
432 functions from each library.
433 </p><pre class="programlisting">
434 gcc test.c -g -O2 -L. -lone -ltwo /usr/lib/libstdc++.so.5 /usr/lib/libstdc++.so.6
436 Which gives the expected:
437 </p><pre class="screen">
438 <code class="computeroutput">
440 libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0x00764000)
441 libstdc++.so.6 => /usr/lib/libstdc++.so.6 (0x40015000)
442 libc.so.6 => /lib/tls/libc.so.6 (0x0036d000)
443 libm.so.6 => /lib/tls/libm.so.6 (0x004a8000)
444 libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x400e5000)
445 /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000)
448 This resulting binary, when executed, will be able to safely use
449 code from both liba, and the dependent libstdc++.so.6, and libb,
450 with the dependent libstdc++.so.5.
451 </p></div></div><div class="sect2" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="abi.issues"></a>Outstanding Issues</h3></div></div></div><p>
452 Some features in the C++ language make versioning especially
453 difficult. In particular, compiler generated constructs such as
454 implicit instantiations for templates, typeinfo information, and
455 virtual tables all may cause ABI leakage across shared library
456 boundaries. Because of this, mixing C++ ABIs is not recommended at
459 For more background on this issue, see these bugzilla entries:
461 <a class="ulink" href="http://gcc.gnu.org/PR24660" target="_top">24660: versioning weak symbols in libstdc++</a>
463 <a class="ulink" href="http://gcc.gnu.org/PR19664" target="_top">19664: libstdc++ headers should have pop/push of the visibility around the declarations</a>
464 </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="id571553"></a><p><span class="title"><i>
465 ABIcheck, a vague idea of checking ABI compatibility
466 </i>. </span><span class="biblioid">
467 <a class="ulink" href="http://abicheck.sourceforge.net/" target="_top">
469 . </span></p></div><div class="biblioentry"><a id="id571570"></a><p><span class="title"><i>
471 </i>. </span><span class="biblioid">
472 <a class="ulink" href="http://www.codesourcery.com/cxx-abi" target="_top">
474 . </span></p></div><div class="biblioentry"><a id="id571588"></a><p><span class="title"><i>
475 Intel® Compilers for Linux* -Compatibility with the GNU Compilers
476 </i>. </span><span class="biblioid">
477 <a class="ulink" href="http://developer.intel.com/software/products/compilers/techtopics/LinuxCompilersCompatibility.htm" target="_top">
479 . </span></p></div><div class="biblioentry"><a id="id571606"></a><p><span class="title"><i>
480 Intel® Compilers for Linux* -Compatibility with the GNU Compilers
481 </i>. </span><span class="biblioid">
482 <a class="ulink" href="http://developer.intel.com/software/products/compilers/techtopics/LinuxCompilersCompatibility.htm" target="_top">
484 . </span></p></div><div class="biblioentry"><a id="id571623"></a><p><span class="title"><i>
485 Sun Solaris 2.9 : Linker and Libraries Guide (document 816-1386)
486 </i>. </span><span class="biblioid">
487 <a class="ulink" href="http://docs.sun.com/?p=/doc/816-1386&a=load" target="_top">
489 . </span></p></div><div class="biblioentry"><a id="id571640"></a><p><span class="title"><i>
490 Sun Solaris 2.9 : C++ Migration Guide (document 816-2459)
491 </i>. </span><span class="biblioid">
492 <a class="ulink" href="http://docs.sun.com/db/prod/solaris.9" target="_top">
494 . </span></p></div><div class="biblioentry"><a id="id571658"></a><p><span class="title"><i>
495 ELF Symbol Versioning
496 </i>. </span><span class="author"><span class="firstname">Ulrich</span> <span class="surname">Drepper</span>. </span><span class="biblioid">
497 <a class="ulink" href="http://people.redhat.com/drepper/symbol-versioning" target="_top">
499 . </span></p></div><div class="biblioentry"><a id="id571686"></a><p><span class="title"><i>
500 C++ ABI for the ARM Architecture
501 </i>. </span><span class="biblioid">
502 <a class="ulink" href="http://www.arm.com/miscPDFs/8033.pdf" target="_top">
504 . </span></p></div><div class="biblioentry"><a id="id571703"></a><p><span class="title"><i>
505 Dynamic Shared Objects: Survey and Issues
506 </i>. </span><span class="subtitle">
508 . </span><span class="author"><span class="firstname">Benjamin</span> <span class="surname">Kosnik</span>. </span><span class="biblioid">
509 <a class="ulink" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1976.html" target="_top">
511 . </span></p></div><div class="biblioentry"><a id="id571735"></a><p><span class="title"><i>
512 Versioning With Namespaces
513 </i>. </span><span class="subtitle">
515 . </span><span class="author"><span class="firstname">Benjamin</span> <span class="surname">Kosnik</span>. </span><span class="biblioid">
516 <a class="ulink" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n2013.html" target="_top">
518 . </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="internals.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">Porting to New Hardware or Operating Systems </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> API Evolution and Deprecation History</td></tr></table></div></body></html>