OpenCores
URL https://opencores.org/ocsvn/scarts/scarts/trunk

Subversion Repositories scarts

[/] [scarts/] [trunk/] [toolchain/] [scarts-gcc/] [gcc-4.1.1/] [libstdc++-v3/] [docs/] [html/] [abi.html] - Blame information for rev 20

Details | Compare with Previous | View Log

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

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.