1 <sect1 id="appendix.porting.abi" xreflabel="abi">
2 <?dbhtml filename="abi.html"?>
24 <title>ABI Policy and Guidelines</title>
29 <sect2 id="abi.cxx_interface" xreflabel="abi.cxx_interface">
30 <title>The C++ Interface</title>
33 C++ applications often dependent on specific language support
34 routines, say for throwing exceptions, or catching exceptions, and
35 perhaps also dependent on features in the C++ Standard Library.
39 The C++ Standard Library has many include files, types defined in
40 those include files, specific named functions, and other
41 behavior. The text of these behaviors, as written in source include
42 files, is called the Application Programing Interface, or API.
46 Furthermore, C++ source that is compiled into object files is
47 transformed by the compiler: it arranges objects with specific
48 alignment and in a particular layout, mangling names according to a
49 well-defined algorithm, has specific arrangements for the support of
50 virtual functions, etc. These details are defined as the compiler
51 Application Binary Interface, or ABI. The GNU C++ compiler uses an
52 industry-standard C++ ABI starting with version 3. Details can be
54 url="http://www.codesourcery.com/cxx-abi/abi.html"> ABI
55 specification</ulink>.
59 The GNU C++ compiler, g++, has a compiler command line option to
60 switch between various different C++ ABIs. This explicit version
61 switch is the flag <code>-fabi-version</code>. In addition, some
62 g++ command line options may change the ABI as a side-effect of
63 use. Such flags include <code>-fpack-struct</code> and
64 <code>-fno-exceptions</code>, but include others: see the complete
65 list in the GCC manual under the heading <ulink url="http://gcc.gnu.org/onlinedocs/gcc/Code-Gen-Options.html#Code%20Gen%20Options">Options
66 for Code Generation Conventions</ulink>.
70 The configure options used when building a specific libstdc++
71 version may also impact the resulting library ABI. The available
72 configure options, and their impact on the library ABI, are
74 <link linkend="manual.intro.setup.configure">here</link>.
77 <para> Putting all of these ideas together results in the C++ Standard
78 library ABI, which is the compilation of a given library API by a
79 given compiler ABI. In a nutshell:
84 library API + compiler ABI = library ABI
89 The library ABI is mostly of interest for end-users who have
90 unresolved symbols and are linking dynamically to the C++ Standard
91 library, and who thus must be careful to compile their application
92 with a compiler that is compatible with the available C++ Standard
93 library binary. In this case, compatible is defined with the equation
94 above: given an application compiled with a given compiler ABI and
95 library API, it will work correctly with a Standard C++ Library
96 created with the same constraints.
100 To use a specific version of the C++ ABI, one must use a
101 corresponding GNU C++ toolchain (i.e., g++ and libstdc++) that
102 implements the C++ ABI in question.
107 <sect2 id="abi.versioning" xreflabel="abi.versioning">
108 <title>Versioning</title>
110 <para> The C++ interface has evolved throughout the history of the GNU
111 C++ toolchain. With each release, various details have been changed so
112 as to give distinct versions to the C++ interface.
115 <sect3 id="abi.versioning.goals" xreflabel="abi.versioning.goals">
118 <para>Extending existing, stable ABIs. Versioning gives subsequent
119 releases of library binaries the ability to add new symbols and add
120 functionality, all the while retaining compatibility with the previous
121 releases in the series. Thus, program binaries linked with the initial
122 release of a library binary will still link correctly if the library
123 binary is replaced by carefully-managed subsequent library
124 binaries. This is called forward compatibility.
127 The reverse (backwards compatibility) is not true. It is not possible
128 to take program binaries linked with the latest version of a library
129 binary in a release series (with additional symbols added), substitute
130 in the initial release of the library binary, and remain link
134 <para>Allows multiple, incompatible ABIs to coexist at the same time.
138 <sect3 id="abi.versioning.history" xreflabel="abi.versioning.history">
139 <title>History</title>
142 How can this complexity be managed? What does C++ versioning mean?
143 Because library and compiler changes often make binaries compiled
144 with one version of the GNU tools incompatible with binaries
145 compiled with other (either newer or older) versions of the same GNU
146 tools, specific techniques are used to make managing this complexity
151 The following techniques are used:
156 <listitem><para>Release versioning on the libgcc_s.so binary. </para>
158 <para>This is implemented via file names and the ELF
159 <constant>DT_SONAME</constant> mechanism (at least on ELF
160 systems). It is versioned as follows:
164 <listitem><para>gcc-3.0.0: libgcc_s.so.1</para></listitem>
165 <listitem><para>gcc-3.0.1: libgcc_s.so.1</para></listitem>
166 <listitem><para>gcc-3.0.2: libgcc_s.so.1</para></listitem>
167 <listitem><para>gcc-3.0.3: libgcc_s.so.1</para></listitem>
168 <listitem><para>gcc-3.0.4: libgcc_s.so.1</para></listitem>
169 <listitem><para>gcc-3.1.0: libgcc_s.so.1</para></listitem>
170 <listitem><para>gcc-3.1.1: libgcc_s.so.1</para></listitem>
171 <listitem><para>gcc-3.2.0: libgcc_s.so.1</para></listitem>
172 <listitem><para>gcc-3.2.1: libgcc_s.so.1</para></listitem>
173 <listitem><para>gcc-3.2.2: libgcc_s.so.1</para></listitem>
174 <listitem><para>gcc-3.2.3: libgcc_s.so.1</para></listitem>
175 <listitem><para>gcc-3.3.0: libgcc_s.so.1</para></listitem>
176 <listitem><para>gcc-3.3.1: libgcc_s.so.1</para></listitem>
177 <listitem><para>gcc-3.3.2: libgcc_s.so.1</para></listitem>
178 <listitem><para>gcc-3.3.3: libgcc_s.so.1</para></listitem>
179 <listitem><para>gcc-3.4.x, gcc-4.[0-3].x: on m68k-linux and
180 hppa-linux this is either libgcc_s.so.1 (when configuring
181 <code>--with-sjlj-exceptions</code>) or libgcc_s.so.2. For all
182 others, this is libgcc_s.so.1. </para>
188 <listitem><para>Symbol versioning on the libgcc_s.so binary.</para>
190 <para>It is versioned with the following labels and version
191 definitions, where the version definition is the maximum for a
192 particular release. Labels are cumulative. If a particular release
193 is not listed, it has the same version labels as the preceding
196 <para>This corresponds to the mapfile: gcc/libgcc-std.ver</para>
198 <listitem><para>gcc-3.0.0: GCC_3.0</para></listitem>
199 <listitem><para>gcc-3.3.0: GCC_3.3</para></listitem>
200 <listitem><para>gcc-3.3.1: GCC_3.3.1</para></listitem>
201 <listitem><para>gcc-3.3.2: GCC_3.3.2</para></listitem>
202 <listitem><para>gcc-3.3.4: GCC_3.3.4</para></listitem>
203 <listitem><para>gcc-3.4.0: GCC_3.4</para></listitem>
204 <listitem><para>gcc-3.4.2: GCC_3.4.2</para></listitem>
205 <listitem><para>gcc-3.4.4: GCC_3.4.4</para></listitem>
206 <listitem><para>gcc-4.0.0: GCC_4.0.0</para></listitem>
207 <listitem><para>gcc-4.1.0: GCC_4.1.0</para></listitem>
208 <listitem><para>gcc-4.2.0: GCC_4.2.0</para></listitem>
209 <listitem><para>gcc-4.3.0: GCC_4.3.0</para></listitem>
210 <listitem><para>gcc-4.4.0: GCC_4.4.0</para></listitem>
216 Release versioning on the libstdc++.so binary, implemented in
217 the same was as the libgcc_s.so binary above. Listed is the
218 filename: <constant>DT_SONAME</constant> can be deduced from
219 the filename by removing the last two period-delimited numbers. For
220 example, filename <filename>libstdc++.so.5.0.4</filename>
221 corresponds to a <constant>DT_SONAME</constant> of
222 <constant>libstdc++.so.5</constant>. Binaries with equivalent
223 <constant>DT_SONAME</constant>s are forward-compatibile: in
224 the table below, releases incompatible with the previous
225 one are explicitly noted.
228 <para>It is versioned as follows:
231 <listitem><para>gcc-3.0.0: libstdc++.so.3.0.0</para></listitem>
232 <listitem><para>gcc-3.0.1: libstdc++.so.3.0.1</para></listitem>
233 <listitem><para>gcc-3.0.2: libstdc++.so.3.0.2</para></listitem>
234 <listitem><para>gcc-3.0.3: libstdc++.so.3.0.2 (See Note 1)</para></listitem>
235 <listitem><para>gcc-3.0.4: libstdc++.so.3.0.4</para></listitem>
236 <listitem><para>gcc-3.1.0: libstdc++.so.4.0.0 <emphasis>(Incompatible with previous)</emphasis></para></listitem>
237 <listitem><para>gcc-3.1.1: libstdc++.so.4.0.1</para></listitem>
238 <listitem><para>gcc-3.2.0: libstdc++.so.5.0.0 <emphasis>(Incompatible with previous)</emphasis></para></listitem>
239 <listitem><para>gcc-3.2.1: libstdc++.so.5.0.1</para></listitem>
240 <listitem><para>gcc-3.2.2: libstdc++.so.5.0.2</para></listitem>
241 <listitem><para>gcc-3.2.3: libstdc++.so.5.0.3 (See Note 2)</para></listitem>
242 <listitem><para>gcc-3.3.0: libstdc++.so.5.0.4</para></listitem>
243 <listitem><para>gcc-3.3.1: libstdc++.so.5.0.5</para></listitem>
244 <listitem><para>gcc-3.3.2: libstdc++.so.5.0.5</para></listitem>
245 <listitem><para>gcc-3.3.3: libstdc++.so.5.0.5</para></listitem>
246 <listitem><para>gcc-3.4.0: libstdc++.so.6.0.0 <emphasis>(Incompatible with previous)</emphasis></para></listitem>
247 <listitem><para>gcc-3.4.1: libstdc++.so.6.0.1</para></listitem>
248 <listitem><para>gcc-3.4.2: libstdc++.so.6.0.2</para></listitem>
249 <listitem><para>gcc-3.4.3: libstdc++.so.6.0.3</para></listitem>
250 <listitem><para>gcc-3.4.4: libstdc++.so.6.0.3</para></listitem>
251 <listitem><para>gcc-3.4.5: libstdc++.so.6.0.3</para></listitem>
252 <listitem><para>gcc-3.4.6: libstdc++.so.6.0.3</para></listitem>
253 <listitem><para>gcc-4.0.0: libstdc++.so.6.0.4</para></listitem>
254 <listitem><para>gcc-4.0.1: libstdc++.so.6.0.5</para></listitem>
255 <listitem><para>gcc-4.0.2: libstdc++.so.6.0.6</para></listitem>
256 <listitem><para>gcc-4.0.3: libstdc++.so.6.0.7</para></listitem>
257 <listitem><para>gcc-4.1.0: libstdc++.so.6.0.7</para></listitem>
258 <listitem><para>gcc-4.1.1: libstdc++.so.6.0.8</para></listitem>
259 <listitem><para>gcc-4.1.2: libstdc++.so.6.0.8</para></listitem>
260 <listitem><para>gcc-4.2.0: libstdc++.so.6.0.9</para></listitem>
261 <listitem><para>gcc-4.2.1: libstdc++.so.6.0.9 (See Note 3)</para></listitem>
262 <listitem><para>gcc-4.2.2: libstdc++.so.6.0.9</para></listitem>
263 <listitem><para>gcc-4.2.3: libstdc++.so.6.0.9</para></listitem>
264 <listitem><para>gcc-4.2.4: libstdc++.so.6.0.9</para></listitem>
265 <listitem><para>gcc-4.3.0: libstdc++.so.6.0.10</para></listitem>
266 <listitem><para>gcc-4.3.1: libstdc++.so.6.0.10</para></listitem>
267 <listitem><para>gcc-4.3.2: libstdc++.so.6.0.10</para></listitem>
268 <listitem><para>gcc-4.3.3: libstdc++.so.6.0.10</para></listitem>
269 <listitem><para>gcc-4.4.0: libstdc++.so.6.0.11</para></listitem>
272 Note 1: Error should be libstdc++.so.3.0.3.
275 Note 2: Not strictly required.
278 Note 3: This release (but not previous or subsequent) has one
279 known incompatibility, see <ulink
280 url="http://gcc.gnu.org/bugzilla/show_bug.cgi?id=33678">33678</ulink>
281 in the GCC bug database.
285 <listitem><para>Symbol versioning on the libstdc++.so binary.</para>
287 <para>mapfile: libstdc++/config/linker-map.gnu</para>
288 <para>It is versioned with the following labels and version
289 definitions, where the version definition is the maximum for a
290 particular release. Note, only symbol which are newly introduced
291 will use the maximum version definition. Thus, for release series
292 with the same label, but incremented version definitions, the later
293 release has both versions. (An example of this would be the
294 gcc-3.2.1 release, which has GLIBCPP_3.2.1 for new symbols and
295 GLIBCPP_3.2 for symbols that were introduced in the gcc-3.2.0
296 release.) If a particular release is not listed, it has the same
297 version labels as the preceding release.
300 <listitem><para>gcc-3.0.0: (Error, not versioned)</para></listitem>
301 <listitem><para>gcc-3.0.1: (Error, not versioned)</para></listitem>
302 <listitem><para>gcc-3.0.2: (Error, not versioned)</para></listitem>
303 <listitem><para>gcc-3.0.3: (Error, not versioned)</para></listitem>
304 <listitem><para>gcc-3.0.4: (Error, not versioned)</para></listitem>
305 <listitem><para>gcc-3.1.0: GLIBCPP_3.1, CXXABI_1</para></listitem>
306 <listitem><para>gcc-3.1.1: GLIBCPP_3.1, CXXABI_1</para></listitem>
307 <listitem><para>gcc-3.2.0: GLIBCPP_3.2, CXXABI_1.2</para></listitem>
308 <listitem><para>gcc-3.2.1: GLIBCPP_3.2.1, CXXABI_1.2</para></listitem>
309 <listitem><para>gcc-3.2.2: GLIBCPP_3.2.2, CXXABI_1.2</para></listitem>
310 <listitem><para>gcc-3.2.3: GLIBCPP_3.2.2, CXXABI_1.2</para></listitem>
311 <listitem><para>gcc-3.3.0: GLIBCPP_3.2.2, CXXABI_1.2.1</para></listitem>
312 <listitem><para>gcc-3.3.1: GLIBCPP_3.2.3, CXXABI_1.2.1</para></listitem>
313 <listitem><para>gcc-3.3.2: GLIBCPP_3.2.3, CXXABI_1.2.1</para></listitem>
314 <listitem><para>gcc-3.3.3: GLIBCPP_3.2.3, CXXABI_1.2.1</para></listitem>
315 <listitem><para>gcc-3.4.0: GLIBCXX_3.4, CXXABI_1.3</para></listitem>
316 <listitem><para>gcc-3.4.1: GLIBCXX_3.4.1, CXXABI_1.3</para></listitem>
317 <listitem><para>gcc-3.4.2: GLIBCXX_3.4.2</para></listitem>
318 <listitem><para>gcc-3.4.3: GLIBCXX_3.4.3</para></listitem>
319 <listitem><para>gcc-4.0.0: GLIBCXX_3.4.4, CXXABI_1.3.1</para></listitem>
320 <listitem><para>gcc-4.0.1: GLIBCXX_3.4.5</para></listitem>
321 <listitem><para>gcc-4.0.2: GLIBCXX_3.4.6</para></listitem>
322 <listitem><para>gcc-4.0.3: GLIBCXX_3.4.7</para></listitem>
323 <listitem><para>gcc-4.1.1: GLIBCXX_3.4.8</para></listitem>
324 <listitem><para>gcc-4.2.0: GLIBCXX_3.4.9</para></listitem>
325 <listitem><para>gcc-4.3.0: GLIBCXX_3.4.10, CXXABI_1.3.2</para></listitem>
326 <listitem><para>gcc-4.4.0: GLIBCXX_3.4.11, CXXABI_1.3.3</para></listitem>
331 <para>Incremental bumping of a compiler pre-defined macro,
332 __GXX_ABI_VERSION. This macro is defined as the version of the
333 compiler v3 ABI, with g++ 3.0.x being version 100. This macro will
334 be automatically defined whenever g++ is used (the curious can
335 test this by invoking g++ with the '-v' flag.)
339 This macro was defined in the file "lang-specs.h" in the gcc/cp directory.
340 Later versions defined it in "c-common.c" in the gcc directory, and from
341 G++ 3.4 it is defined in c-cppbuiltin.c and its value determined by the
342 '-fabi-version' command line option.
346 It is versioned as follows, where 'n' is given by '-fabi-version=n':
349 <listitem><para>gcc-3.0.x: 100</para></listitem>
350 <listitem><para>gcc-3.1.x: 100 (Error, should be 101)</para></listitem>
351 <listitem><para>gcc-3.2.x: 102</para></listitem>
352 <listitem><para>gcc-3.3.x: 102</para></listitem>
353 <listitem><para>gcc-3.4.x, gcc-4.[0-3].x: 102 (when n=1)</para></listitem>
354 <listitem><para>gcc-3.4.x, gcc-4.[0-3].x: 1000 + n (when n>1) </para></listitem>
355 <listitem><para>gcc-3.4.x, gcc-4.[0-3].x: 999999 (when n=0)</para></listitem>
361 <para>Changes to the default compiler option for
362 <code>-fabi-version</code>.
365 It is versioned as follows:
368 <listitem><para>gcc-3.0.x: (Error, not versioned) </para></listitem>
369 <listitem><para>gcc-3.1.x: (Error, not versioned) </para></listitem>
370 <listitem><para>gcc-3.2.x: <code>-fabi-version=1</code></para></listitem>
371 <listitem><para>gcc-3.3.x: <code>-fabi-version=1</code></para></listitem>
372 <listitem><para>gcc-3.4.x, gcc-4.[0-3].x: <code>-fabi-version=2</code> <emphasis>(Incompatible with previous)</emphasis></para></listitem>
378 <para>Incremental bumping of a library pre-defined macro. For releases
379 before 3.4.0, the macro is __GLIBCPP__. For later releases, it's
380 __GLIBCXX__. (The libstdc++ project generously changed from CPP to
381 CXX throughout its source to allow the "C" pre-processor the CPP
382 macro namespace.) These macros are defined as the date the library
383 was released, in compressed ISO date format, as an unsigned long.
387 This macro is defined in the file "c++config" in the
388 "libstdc++/include/bits" directory. (Up to gcc-4.1.0, it was
389 changed every night by an automated script. Since gcc-4.1.0, it is
390 the same value as gcc/DATESTAMP.)
393 It is versioned as follows:
396 <listitem><para>gcc-3.0.0: 20010615</para></listitem>
397 <listitem><para>gcc-3.0.1: 20010819</para></listitem>
398 <listitem><para>gcc-3.0.2: 20011023</para></listitem>
399 <listitem><para>gcc-3.0.3: 20011220</para></listitem>
400 <listitem><para>gcc-3.0.4: 20020220</para></listitem>
401 <listitem><para>gcc-3.1.0: 20020514</para></listitem>
402 <listitem><para>gcc-3.1.1: 20020725</para></listitem>
403 <listitem><para>gcc-3.2.0: 20020814</para></listitem>
404 <listitem><para>gcc-3.2.1: 20021119</para></listitem>
405 <listitem><para>gcc-3.2.2: 20030205</para></listitem>
406 <listitem><para>gcc-3.2.3: 20030422</para></listitem>
407 <listitem><para>gcc-3.3.0: 20030513</para></listitem>
408 <listitem><para>gcc-3.3.1: 20030804</para></listitem>
409 <listitem><para>gcc-3.3.2: 20031016</para></listitem>
410 <listitem><para>gcc-3.3.3: 20040214</para></listitem>
411 <listitem><para>gcc-3.4.0: 20040419</para></listitem>
412 <listitem><para>gcc-3.4.1: 20040701</para></listitem>
413 <listitem><para>gcc-3.4.2: 20040906</para></listitem>
414 <listitem><para>gcc-3.4.3: 20041105</para></listitem>
415 <listitem><para>gcc-3.4.4: 20050519</para></listitem>
416 <listitem><para>gcc-3.4.5: 20051201</para></listitem>
417 <listitem><para>gcc-3.4.6: 20060306</para></listitem>
418 <listitem><para>gcc-4.0.0: 20050421</para></listitem>
419 <listitem><para>gcc-4.0.1: 20050707</para></listitem>
420 <listitem><para>gcc-4.0.2: 20050921</para></listitem>
421 <listitem><para>gcc-4.0.3: 20060309</para></listitem>
422 <listitem><para>gcc-4.1.0: 20060228</para></listitem>
423 <listitem><para>gcc-4.1.1: 20060524</para></listitem>
424 <listitem><para>gcc-4.1.2: 20070214</para></listitem>
425 <listitem><para>gcc-4.2.0: 20070514</para></listitem>
426 <listitem><para>gcc-4.2.1: 20070719</para></listitem>
427 <listitem><para>gcc-4.2.2: 20071007</para></listitem>
428 <listitem><para>gcc-4.2.3: 20080201</para></listitem>
429 <listitem><para>gcc-4.2.4: 20080519</para></listitem>
430 <listitem><para>gcc-4.3.0: 20080306</para></listitem>
431 <listitem><para>gcc-4.3.1: 20080606</para></listitem>
432 <listitem><para>gcc-4.3.2: 20080827</para></listitem>
433 <listitem><para>gcc-4.3.3: 20090124</para></listitem>
434 <listitem><para>gcc-4.4.0: 20090421</para></listitem>
441 Incremental bumping of a library pre-defined macro,
442 _GLIBCPP_VERSION. This macro is defined as the released version of
443 the library, as a string literal. This is only implemented in
444 gcc-3.1.0 releases and higher, and is deprecated in 3.4 (where it
445 is called _GLIBCXX_VERSION).
449 This macro is defined in the file "c++config" in the
450 "libstdc++/include/bits" directory and is generated
451 automatically by autoconf as part of the configure-time generation
456 It is versioned as follows:
459 <listitem><para>gcc-3.0.0: "3.0.0"</para></listitem>
460 <listitem><para>gcc-3.0.1: "3.0.0" (Error, should be "3.0.1")</para></listitem>
461 <listitem><para>gcc-3.0.2: "3.0.0" (Error, should be "3.0.2")</para></listitem>
462 <listitem><para>gcc-3.0.3: "3.0.0" (Error, should be "3.0.3")</para></listitem>
463 <listitem><para>gcc-3.0.4: "3.0.0" (Error, should be "3.0.4")</para></listitem>
464 <listitem><para>gcc-3.1.0: "3.1.0"</para></listitem>
465 <listitem><para>gcc-3.1.1: "3.1.1"</para></listitem>
466 <listitem><para>gcc-3.2.0: "3.2"</para></listitem>
467 <listitem><para>gcc-3.2.1: "3.2.1"</para></listitem>
468 <listitem><para>gcc-3.2.2: "3.2.2"</para></listitem>
469 <listitem><para>gcc-3.2.3: "3.2.3"</para></listitem>
470 <listitem><para>gcc-3.3.0: "3.3"</para></listitem>
471 <listitem><para>gcc-3.3.1: "3.3.1"</para></listitem>
472 <listitem><para>gcc-3.3.2: "3.3.2"</para></listitem>
473 <listitem><para>gcc-3.3.3: "3.3.3"</para></listitem>
474 <listitem><para>gcc-3.4.x: "version-unused"</para></listitem>
475 <listitem><para>gcc-4.[0-3].x: "version-unused"</para></listitem>
482 Matching each specific C++ compiler release to a specific set of
483 C++ include files. This is only implemented in gcc-3.1.1 releases
487 All C++ includes are installed in include/c++, then nest in a
488 directory hierarchy corresponding to the C++ compiler's released
489 version. This version corresponds to the variable "gcc_version" in
490 "libstdc++/acinclude.m4," and more details can be found in that
491 file's macro GLIBCXX_CONFIGURE (GLIBCPP_CONFIGURE before gcc-3.4.0).
494 C++ includes are versioned as follows:
497 <listitem><para>gcc-3.0.0: include/g++-v3</para></listitem>
498 <listitem><para>gcc-3.0.1: include/g++-v3</para></listitem>
499 <listitem><para>gcc-3.0.2: include/g++-v3</para></listitem>
500 <listitem><para>gcc-3.0.3: include/g++-v3</para></listitem>
501 <listitem><para>gcc-3.0.4: include/g++-v3</para></listitem>
502 <listitem><para>gcc-3.1.0: include/g++-v3</para></listitem>
503 <listitem><para>gcc-3.1.1: include/c++/3.1.1</para></listitem>
504 <listitem><para>gcc-3.2.0: include/c++/3.2</para></listitem>
505 <listitem><para>gcc-3.2.1: include/c++/3.2.1</para></listitem>
506 <listitem><para>gcc-3.2.2: include/c++/3.2.2</para></listitem>
507 <listitem><para>gcc-3.2.3: include/c++/3.2.3</para></listitem>
508 <listitem><para>gcc-3.3.0: include/c++/3.3</para></listitem>
509 <listitem><para>gcc-3.3.1: include/c++/3.3.1</para></listitem>
510 <listitem><para>gcc-3.3.2: include/c++/3.3.2</para></listitem>
511 <listitem><para>gcc-3.3.3: include/c++/3.3.3</para></listitem>
512 <listitem><para>gcc-3.4.0: include/c++/3.4.0</para></listitem>
513 <listitem><para>gcc-3.4.1: include/c++/3.4.1</para></listitem>
514 <listitem><para>gcc-3.4.2: include/c++/3.4.2</para></listitem>
515 <listitem><para>gcc-3.4.3: include/c++/3.4.3</para></listitem>
516 <listitem><para>gcc-3.4.4: include/c++/3.4.4</para></listitem>
517 <listitem><para>gcc-3.4.5: include/c++/3.4.5</para></listitem>
518 <listitem><para>gcc-3.4.6: include/c++/3.4.6</para></listitem>
519 <listitem><para>gcc-4.0.0: include/c++/4.0.0</para></listitem>
520 <listitem><para>gcc-4.0.1: include/c++/4.0.1</para></listitem>
521 <listitem><para>gcc-4.0.2: include/c++/4.0.2</para></listitem>
522 <listitem><para>gcc-4.0.3: include/c++/4.0.3</para></listitem>
523 <listitem><para>gcc-4.1.0: include/c++/4.1.0</para></listitem>
524 <listitem><para>gcc-4.1.1: include/c++/4.1.1</para></listitem>
525 <listitem><para>gcc-4.1.2: include/c++/4.1.2</para></listitem>
526 <listitem><para>gcc-4.2.0: include/c++/4.2.0</para></listitem>
527 <listitem><para>gcc-4.2.1: include/c++/4.2.1</para></listitem>
528 <listitem><para>gcc-4.2.2: include/c++/4.2.2</para></listitem>
529 <listitem><para>gcc-4.2.3: include/c++/4.2.3</para></listitem>
530 <listitem><para>gcc-4.2.4: include/c++/4.2.4</para></listitem>
531 <listitem><para>gcc-4.3.0: include/c++/4.3.0</para></listitem>
532 <listitem><para>gcc-4.3.1: include/c++/4.3.1</para></listitem>
533 <listitem><para>gcc-4.3.3: include/c++/4.3.3</para></listitem>
534 <listitem><para>gcc-4.4.0: include/c++/4.4.0</para></listitem>
541 Taken together, these techniques can accurately specify interface
542 and implementation changes in the GNU C++ tools themselves. Used
543 properly, they allow both the GNU C++ tools implementation, and
544 programs using them, an evolving yet controlled development that
545 maintains backward compatibility.
551 <sect3 id="abi.versioning.prereq" xreflabel="abi.versioning.prereq">
552 <title>Prerequisites</title>
554 Minimum environment that supports a versioned ABI: A supported
555 dynamic linker, a GNU linker of sufficient vintage to understand
556 demangled C++ name globbing (ld), a shared executable compiled
557 with g++, and shared libraries (libgcc_s, libstdc++) compiled by
558 a compiler (g++) with a compatible ABI. Phew.
562 On top of all that, an additional constraint: libstdc++ did not
563 attempt to version symbols (or age gracefully, really) until
568 Most modern Linux and BSD versions, particularly ones using
569 gcc-3.1.x tools and more recent vintages, will meet the
574 <sect3 id="abi.versioning.config" xreflabel="abi.versioning.config">
575 <title>Configuring</title>
578 It turns out that most of the configure options that change
579 default behavior will impact the mangled names of exported
580 symbols, and thus impact versioning and compatibility.
584 For more information on configure options, including ABI
586 http://gcc.gnu.org/onlinedocs/libstdc++/configopts.html
590 There is one flag that explicitly deals with symbol versioning:
595 In particular, libstdc++/acinclude.m4 has a macro called
596 GLIBCXX_ENABLE_SYMVERS that defaults to yes (or the argument
597 passed in via --enable-symvers=foo). At that point, the macro
598 attempts to make sure that all the requirement for symbol
599 versioning are in place. For more information, please consult
604 <sect3 id="abi.versioning.active" xreflabel="abi.versioning.active">
605 <title>Checking Active</title>
608 When the GNU C++ library is being built with symbol versioning
609 on, you should see the following at configure time for
615 checking versioning on shared library symbols... gnu
620 If you don't see this line in the configure output, or if this line
621 appears but the last word is 'no', then you are out of luck.
625 If the compiler is pre-installed, a quick way to test is to compile
626 the following (or any) simple C++ file and link it to the shared
631 #include <iostream>
634 { std::cout << "hello" << std::endl; return 0; }
636 %g++ hello.cc -o hello.out
639 libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0x00764000)
640 libm.so.6 => /lib/tls/libm.so.6 (0x004a8000)
641 libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40016000)
642 libc.so.6 => /lib/tls/libc.so.6 (0x0036d000)
643 /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000)
649 If you see symbols in the resulting output with "GLIBCXX_3" as part
650 of the name, then the executable is versioned. Here's an example:
654 <code>U _ZNSt8ios_base4InitC1Ev@@GLIBCXX_3.4</code>
660 <sect2 id="abi.changes_allowed" xreflabel="abi.changes_allowed">
661 <title>Allowed Changes</title>
664 The following will cause the library minor version number to
665 increase, say from "libstdc++.so.3.0.4" to "libstdc++.so.3.0.5".
668 <listitem><para>Adding an exported global or static data member</para></listitem>
669 <listitem><para>Adding an exported function, static or non-virtual member function</para></listitem>
670 <listitem><para>Adding an exported symbol or symbols by additional instantiations</para></listitem>
673 Other allowed changes are possible.
678 <sect2 id="abi.changes_no" xreflabel="abi.changes_no">
679 <title>Prohibited Changes</title>
682 The following non-exhaustive list will cause the library major version
683 number to increase, say from "libstdc++.so.3.0.4" to
684 "libstdc++.so.4.0.0".
688 <listitem><para>Changes in the gcc/g++ compiler ABI</para></listitem>
689 <listitem><para>Changing size of an exported symbol</para></listitem>
690 <listitem><para>Changing alignment of an exported symbol</para></listitem>
691 <listitem><para>Changing the layout of an exported symbol</para></listitem>
692 <listitem><para>Changing mangling on an exported symbol</para></listitem>
693 <listitem><para>Deleting an exported symbol</para></listitem>
694 <listitem><para>Changing the inheritance properties of a type by adding or removing
695 base classes</para></listitem>
697 Changing the size, alignment, or layout of types
698 specified in the C++ standard. These may not necessarily be
699 instantiated or otherwise exported in the library binary, and
700 include all the required locale facets, as well as things like
701 std::basic_streambuf, et al.
704 <listitem><para> Adding an explicit copy constructor or destructor to a
705 class that would otherwise have implicit versions. This will change
706 the way the compiler deals with this class in by-value return
707 statements or parameters: instead of being passing instances of this
708 class in registers, the compiler will be forced to use memory. See <ulink url="http://www.codesourcery.com/cxx-abi/abi.html#calls"> this part</ulink>
709 of the C++ ABI documentation for further details.
718 <sect2 id="abi.impl" xreflabel="abi.impl">
719 <title>Implementation</title>
724 Separation of interface and implementation
727 This is accomplished by two techniques that separate the API from
728 the ABI: forcing undefined references to link against a library
729 binary for definitions.
734 <term>Include files have declarations, source files have defines</term>
738 For non-templatized types, such as much of <code>class
739 locale</code>, the appropriate standard C++ include, say
740 <code>locale</code>, can contain full declarations, while
741 various source files (say <code> locale.cc, locale_init.cc,
742 localename.cc</code>) contain definitions.
748 <term>Extern template on required types</term>
752 For parts of the standard that have an explicit list of
753 required instantiations, the GNU extension syntax <code> extern
754 template </code> can be used to control where template
755 definitions reside. By marking required instantiations as
756 <code> extern template </code> in include files, and providing
757 explicit instantiations in the appropriate instantiation files,
758 non-inlined template functions can be versioned. This technique
759 is mostly used on parts of the standard that require <code>
760 char</code> and <code> wchar_t</code> instantiations, and
761 includes <code> basic_string</code>, the locale facets, and the
762 types in <code> iostreams</code>.
770 In addition, these techniques have the additional benefit that they
771 reduce binary size, which can increase runtime performance.
777 Namespaces linking symbol definitions to export mapfiles
780 All symbols in the shared library binary are processed by a
781 linker script at build time that either allows or disallows
782 external linkage. Because of this, some symbols, regardless of
783 normal C/C++ linkage, are not visible. Symbols that are internal
784 have several appealing characteristics: by not exporting the
785 symbols, there are no relocations when the shared library is
786 started and thus this makes for faster runtime loading
787 performance by the underlying dynamic loading mechanism. In
788 addition, they have the possibility of changing without impacting
792 <para>The following namespaces are transformed by the mapfile:</para>
797 <term><code>namespace std</code></term>
798 <listitem><para> Defaults to exporting all symbols in label
799 <code>GLIBCXX</code> that do not begin with an underscore, i.e.,
800 <code>__test_func</code> would not be exported by default. Select
801 exceptional symbols are allowed to be visible.</para></listitem>
805 <term><code>namespace __gnu_cxx</code></term>
806 <listitem><para> Defaults to not exporting any symbols in label
807 <code>GLIBCXX</code>, select items are allowed to be visible.</para></listitem>
811 <term><code>namespace __gnu_internal</code></term>
812 <listitem><para> Defaults to not exported, no items are allowed to be visible.</para></listitem>
816 <term><code>namespace __cxxabiv1</code>, aliased to <code> namespace abi</code></term>
817 <listitem><para> Defaults to not exporting any symbols in label
818 <code>CXXABI</code>, select items are allowed to be visible.</para></listitem>
826 <listitem><para>Freezing the API</para>
827 <para>Disallowed changes, as above, are not made on a stable release
828 branch. Enforcement tends to be less strict with GNU extensions that
829 standard includes.</para>
835 <sect2 id="abi.testing" xreflabel="abi.testing">
836 <title>Testing</title>
838 <sect3 id="abi.testing.single" xreflabel="abi.testing.single">
839 <title>Single ABI Testing</title>
842 Testing for GNU C++ ABI changes is composed of two distinct
843 areas: testing the C++ compiler (g++) for compiler changes, and
844 testing the C++ library (libstdc++) for library changes.
848 Testing the C++ compiler ABI can be done various ways.
852 One. Intel ABI checker. More information can be obtained <ulink
853 url="http://developer.intel.com/software/products/opensource/">here.</ulink>
858 The second is yet unreleased, but has been announced on the gcc
859 mailing list. It is yet unspecified if these tools will be freely
860 available, and able to be included in a GNU project. Please contact
861 Mark Mitchell (mark@codesourcery.com) for more details, and current
867 Involves using the vlad.consistency test framework. This has also been
868 discussed on the gcc mailing lists.
872 Testing the C++ library ABI can also be done various ways.
877 (Brendan Kehoe, Jeff Law suggestion to run 'make check-c++' two ways,
878 one with a new compiler and an old library, and the other with an old
879 compiler and a new library, and look for testsuite regressions)
883 Details on how to set this kind of test up can be found here:
884 http://gcc.gnu.org/ml/gcc/2002-08/msg00142.html
889 Use the 'make check-abi' rule in the libstdc++ Makefile.
893 This is a proactive check the library ABI. Currently, exported symbol
894 names that are either weak or defined are checked against a last known
895 good baseline. Currently, this baseline is keyed off of 3.4.0
896 binaries, as this was the last time the .so number was incremented. In
897 addition, all exported names are demangled, and the exported objects
898 are checked to make sure they are the same size as the same object in
901 Notice that each baseline is relative to a <emphasis>default</emphasis>
902 configured library and compiler: in particular, if options such as
903 --enable-clocale, or --with-cpu, in case of multilibs, are used at
904 configure time, the check may fail, either because of substantive
905 differences or because of limitations of the current checking
910 This dataset is insufficient, yet a start. Also needed is a
911 comprehensive check for all user-visible types part of the standard
912 library for sizeof() and alignof() changes.
916 Verifying compatible layouts of objects is not even attempted. It
917 should be possible to use sizeof, alignof, and offsetof to compute
918 offsets for each structure and type in the standard library, saving to
919 another datafile. Then, compute this in a similar way for new
920 binaries, and look for differences.
924 Another approach might be to use the -fdump-class-hierarchy flag to
925 get information. However, currently this approach gives insufficient
926 data for use in library testing, as class data members, their offsets,
927 and other detailed data is not displayed with this flag.
928 (See g++/7470 on how this was used to find bugs.)
932 Perhaps there are other C++ ABI checkers. If so, please notify
933 us. We'd like to know about them!
937 <sect3 id="abi.testing.multi" xreflabel="abi.testing.multi">
938 <title>Multiple ABI Testing</title>
940 A "C" application, dynamically linked to two shared libraries, liba,
941 libb. The dependent library liba is C++ shared library compiled with
942 gcc-3.3.x, and uses io, exceptions, locale, etc. The dependent library
943 libb is a C++ shared library compiled with gcc-3.4.x, and also uses io,
944 exceptions, locale, etc.
947 <para> As above, libone is constructed as follows: </para>
949 %$bld/H-x86-gcc-3.4.0/bin/g++ -fPIC -DPIC -c a.cc
951 %$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
953 %ln -s libone.so.1.0.0 libone.so
955 %$bld/H-x86-gcc-3.4.0/bin/g++ -c a.cc
960 <para> And, libtwo is constructed as follows: </para>
963 %$bld/H-x86-gcc-3.3.3/bin/g++ -fPIC -DPIC -c b.cc
965 %$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
967 %ln -s libtwo.so.1.0.0 libtwo.so
969 %$bld/H-x86-gcc-3.3.3/bin/g++ -c b.cc
974 <para> ...with the resulting libraries looking like </para>
979 libstdc++.so.6 => /usr/lib/libstdc++.so.6 (0x40016000)
980 libm.so.6 => /lib/tls/libm.so.6 (0x400fa000)
981 libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x4011c000)
982 libc.so.6 => /lib/tls/libc.so.6 (0x40125000)
983 /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000)
986 libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0x40027000)
987 libm.so.6 => /lib/tls/libm.so.6 (0x400e1000)
988 libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40103000)
989 libc.so.6 => /lib/tls/libc.so.6 (0x4010c000)
990 /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000)
995 Then, the "C" compiler is used to compile a source file that uses
996 functions from each library.
999 gcc test.c -g -O2 -L. -lone -ltwo /usr/lib/libstdc++.so.5 /usr/lib/libstdc++.so.6
1003 Which gives the expected:
1009 libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0x00764000)
1010 libstdc++.so.6 => /usr/lib/libstdc++.so.6 (0x40015000)
1011 libc.so.6 => /lib/tls/libc.so.6 (0x0036d000)
1012 libm.so.6 => /lib/tls/libm.so.6 (0x004a8000)
1013 libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x400e5000)
1014 /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000)
1019 This resulting binary, when executed, will be able to safely use
1020 code from both liba, and the dependent libstdc++.so.6, and libb,
1021 with the dependent libstdc++.so.5.
1026 <sect2 id="abi.issues" xreflabel="abi.issues">
1027 <title>Outstanding Issues</title>
1030 Some features in the C++ language make versioning especially
1031 difficult. In particular, compiler generated constructs such as
1032 implicit instantiations for templates, typeinfo information, and
1033 virtual tables all may cause ABI leakage across shared library
1034 boundaries. Because of this, mixing C++ ABIs is not recommended at
1039 For more background on this issue, see these bugzilla entries:
1043 <ulink url="http://gcc.gnu.org/PR24660">24660: versioning weak symbols in libstdc++</ulink>
1047 <ulink url="http://gcc.gnu.org/PR19664">19664: libstdc++ headers should have pop/push of the visibility around the declarations</ulink>
1052 <bibliography id="abi.biblio" xreflabel="abi.biblio">
1053 <title>Bibliography</title>
1057 ABIcheck, a vague idea of checking ABI compatibility
1061 <ulink url="http://abicheck.sourceforge.net/">
1072 <ulink url="http://www.codesourcery.com/cxx-abi">
1079 IntelĀ® Compilers for Linux* -Compatibility with the GNU Compilers
1083 <ulink url="http://developer.intel.com/software/products/compilers/techtopics/LinuxCompilersCompatibility.htm">
1090 IntelĀ® Compilers for Linux* -Compatibility with the GNU Compilers
1094 <ulink url="http://developer.intel.com/software/products/compilers/techtopics/LinuxCompilersCompatibility.htm">
1101 Sun Solaris 2.9 : Linker and Libraries Guide (document 816-1386)
1105 <ulink url="http://docs.sun.com/?p=/doc/816-1386&a=load">
1113 Sun Solaris 2.9 : C++ Migration Guide (document 816-2459)
1117 <ulink url="http://docs.sun.com/db/prod/solaris.9">
1124 ELF Symbol Versioning
1128 <firstname>Ulrich</firstname>
1129 <surname>Drepper</surname>
1133 <ulink url="http://people.redhat.com/drepper/symbol-versioning">
1140 C++ ABI for the ARM Architecture
1144 <ulink url="http://www.arm.com/miscPDFs/8033.pdf">
1151 Dynamic Shared Objects: Survey and Issues
1158 <firstname>Benjamin</firstname>
1159 <surname>Kosnik</surname>
1163 <ulink url="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1976.html">
1170 Versioning With Namespaces
1177 <firstname>Benjamin</firstname>
1178 <surname>Kosnik</surname>
1182 <ulink url="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n2013.html">