mirror of
git://gcc.gnu.org/git/gcc.git
synced 2025-01-25 02:14:20 +08:00
51937d2c98
2002-07-24 Benjamin Kosnik <bkoz@redhat.com> PR libstdc++/7286 * libsupc++/new: Add placement delete. * testsuite/18_support/new_delete_placement.cc: New. * docs/html/abi.txt: Fix typos. From-SVN: r55718
195 lines
6.0 KiB
Plaintext
195 lines
6.0 KiB
Plaintext
|
||
===========================
|
||
|
||
See http://gcc.gnu.org/ml/libstdc++/2002-07/msg00054.html for why this
|
||
document exists, why it's incomplete, and what needs to be done still.
|
||
|
||
===========================
|
||
|
||
2002-07-23 Benjamin Kosnik
|
||
|
||
Description of the libstdc++ ABI.
|
||
|
||
I. What is an ABI? What's covered? What's not?
|
||
|
||
- What's the deal with C++? Why can't different compiler's object
|
||
files link with each other? Bug? Feature?
|
||
|
||
- scope of document, of use to system integrators.
|
||
|
||
- compilation includes and linked library binary must match up..
|
||
|
||
- library ABI, compiler ABI different (but effects)
|
||
|
||
- GNU C++ does not have a compiler command line option to switch
|
||
between various different C++ ABIs. For instance, there is no way to
|
||
switch between the gcc-3.0.x ABI, gcc-3.1.x ABI, and the gcc-3.2.x
|
||
ABI during compilation. Other C++ compilers do allow this, and some
|
||
g++ command line options may change the ABI (-fno-exceptions, see
|
||
the complete list), but there is no version switch. Sorry. The GNU
|
||
Project recommends that
|
||
|
||
- shared library only, static is immutable.
|
||
|
||
- Minimum environment that supports a versioned ABI: what's needed? A
|
||
supported dynamic linker, a GNU linker of sufficient vintage to
|
||
understand demangled C++ name globbing (ld), a shared executable
|
||
compiled with g++, and shared libraries (libgcc_s, libstdc++-v3)
|
||
compiled by a compiler (g++) with a compatible ABI. Phew.
|
||
|
||
On top of all that, an additional constraint: libstdc++ did not
|
||
attempt to version symbols (or age gracefully, really) until version
|
||
3.1.0.
|
||
|
||
Most modern Linux and BSD versions, particularly ones using
|
||
gcc-3.1.x tools, will meet the requirements above.
|
||
|
||
- What configure options impact symbol versioning?
|
||
There is only one: --enable-symvers. For more information see:
|
||
http://gcc.gnu.org/onlinedocs/libstdc++/configopts.html
|
||
|
||
In particular, libstdc++-v3/acinclude.m4 has a macro called
|
||
GLIBCPP_ENABLE_SYMVERS that defaults to yes (or the argument passed
|
||
in via --enable-symvers=foo). At that point, the macro attempts to
|
||
make sure that all the requirement for symbol versioning are in
|
||
place. For more information, please consult acinclude.m4.
|
||
|
||
- How can I tell if symbol versioning is, indeed, active?
|
||
|
||
When the GNU C++ library is being built with symbol versioning on,
|
||
you should see the following at configure time for libstdc++-v3:
|
||
|
||
checking versioning on shared library symbols... gnu
|
||
|
||
If you don't see this line in the configure output, or if this line
|
||
appears but the last word is 'no', then you are out of luck.
|
||
|
||
If the compiler is pre-installed, a quick way to test is to compile
|
||
the following (or any) simple C++ file:
|
||
|
||
#include <iostream>
|
||
|
||
int main()
|
||
{ std::cout << "hello" << std::endl; return 0; }
|
||
|
||
%g++ hello.cc -o hello.out
|
||
%nm hello.out
|
||
|
||
If you see symbols in the resulting output with "GLIBCPP_3.x" as part
|
||
of the name, then the executable is versioned. Here's an example:
|
||
|
||
U _ZNSt8ios_base4InitC1Ev@@GLIBCPP_3.1
|
||
|
||
|
||
|
||
|
||
|
||
|
||
II. ABI changes
|
||
|
||
- (anything) changing size of an exported symbol
|
||
|
||
- (anything) changing alignment of an exported symbol
|
||
|
||
- (anything) changing the layout of an exported symbol
|
||
|
||
- (anything) changing mangling on an exported symbol
|
||
|
||
- (anything) adding or deleting an exported symbol
|
||
|
||
|
||
III. Versioning
|
||
|
||
- include files
|
||
|
||
- versioning headers with version, why necessary
|
||
(need to control member/non-member functions, add delete files)
|
||
|
||
- shared library binaries
|
||
|
||
- release versions
|
||
|
||
- libtool versions
|
||
|
||
- when does so version get a bump? what are the options?
|
||
|
||
- how is the link map used?
|
||
|
||
- in an non-abi breaking minor release, how are symbols added?
|
||
removed?
|
||
|
||
- in an abi-breaking major release, what happens? symbol fall back
|
||
|
||
|
||
IV. Testing ABI changes
|
||
|
||
Currently, there is no formal testing for changes in the libstdc++
|
||
ABI. It would be in the best interest of GNU C++ users everywhere to
|
||
have such a test, and work to develop this test is ongoing.
|
||
|
||
There is a formal method for checking the compiler parts of the C++
|
||
ABI, donated by Intel. More information can be obtained
|
||
<a href="http://developer.intel.com/software/products/opensource/">here.</a>
|
||
|
||
To test the library, the following two ideas have been suggested:
|
||
|
||
One.
|
||
(Brendan Kehoe, Jeff Law suggestion to run 'make check-c++' two ways,
|
||
one with a new compiler and an old library, and the other with an old
|
||
compiler and a new library, and look for testsuite regressions)
|
||
|
||
Two.
|
||
Have the libstdc++ testsuite proactive check the library ABI. Probably
|
||
a couple of items would be covered, although perhaps not all would
|
||
need to be done at once for this to be useful. Compute the list of
|
||
names exported in the shared version of libstdc++ binary. Then, save
|
||
this list of names. Have this list of names re-computed for each new
|
||
binary of the same version. Next, use sizeof, alignof, and offset to
|
||
compute offsets for each structure and type in the standard library,
|
||
saving to another datafile. Then, compute this for new binaries, and
|
||
look for differences.
|
||
|
||
The thought is to choose one or both of these approaches, and to use a
|
||
Makefile hook, perhaps 'make check-abi', to add this capability to the
|
||
libstdc++ testsuite.
|
||
|
||
Perhaps there are other Library ABI checkers. If so, please notify us.
|
||
|
||
|
||
V. Issues not directly addressed, and possible suggestions
|
||
|
||
- what to do about multi-ABI systems (nathan scenario)?
|
||
|
||
- compatibility libs
|
||
|
||
--enable-version-specific-runtime-libs
|
||
|
||
- Alexandre Oliva proposal to have extended name attributes, modify ld
|
||
|
||
- directory-level versioning
|
||
|
||
- wrapping C++ API's n "C" to use the C ABI.
|
||
|
||
|
||
V. References
|
||
|
||
ABIcheck, a vauge idea of checking ABI compatibility
|
||
http://abicheck.sourceforge.net/
|
||
|
||
C++ ABI reference
|
||
http://www.codesourcery.com/cxx-abi/
|
||
|
||
Intel ABI documentation
|
||
"Intel<65> Compilers for Linux* -Compatibility with the GNU Compilers"
|
||
(included in icc 6.0)
|
||
|
||
Sun Solaris 2.9 docs
|
||
Linker and Libraries Guide (document 816-1386)
|
||
C++ Migration Guide (document 816-2459)
|
||
http://docs.sun.com/db/prod/solaris.9
|
||
http://docs.sun.com/?p=/doc/816-1386&a=load
|
||
|
||
Ulrich Drepper, "ELF Symbol Versioning"
|
||
http://people.redhat.com/drepper/symbol-versioning
|
||
|