This is the mail archive of the
gcc-patches@gcc.gnu.org
mailing list for the GCC project.
Re: [v3] abi docs, testsuite
- From: Matthias Klose <doko at cs dot tu-berlin dot de>
- To: Benjamin Kosnik <bkoz at redhat dot com>
- Cc: gcc-patches at gcc dot gnu dot org
- Date: Thu, 13 May 2004 23:17:02 +0200
- Subject: Re: [v3] abi docs, testsuite
- References: <20040513083719.28a474db.bkoz@redhat.com>
Benjamin Kosnik writes:
> This adds to the existing abi documentation, based on questions by
> Mark Mitchell, Matt Austern, Michael Werz and others.
>
> Thanks to Ulrich for reviewing the drafts.
>
> tested x86/linux
>
> -benjamin
>
> 2004-05-12 Benjamin Kosnik <bkoz@redhat.com>
>
> * docs/html/abi.html: New.
> * docs/html/abi.txt: Remove.
> * docs/html/documentation.html: Add link.
> * testsuite/Makefile.am: Add files.
> * testsuite/Makefile.in: Regenerated.
> * testsuite/abi_check.cc: Move and modify code into...
> * testsuite/testsuite_abi.cc: Add.
> * testsuite/testsuite_abi.h: Add.
>
> * docs/html/17_intro/TODO: Update.
> * include/bits/stl_pair.h: Format.
>
> Index: docs/html/abi.html
> ===================================================================
> RCS file: docs/html/abi.html
> diff -N docs/html/abi.html
> *** /dev/null 1 Jan 1970 00:00:00 -0000
> --- docs/html/abi.html 13 May 2004 00:39:13 -0000
> ***************
> *** 0 ****
> --- 1,857 ----
> + <?xml version="1.0" encoding="ISO-8859-1"?>
> + <!DOCTYPE html
> + PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
> + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
> +
> + <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
> + <head>
> + <meta name="AUTHOR" content="bkoz@gcc.gnu.org (Benjamin Kosnik)" />
> + <meta name="KEYWORDS" content="C++, libstdc++, dynamic, shared, library, ABI, version" />
> + <meta name="DESCRIPTION" content="C++ Standard Library ABI" />
> + <meta name="GENERATOR" content="emacs and ten fingers" />
> + <title>Standard C++ Library ABI</title>
> + <link rel="StyleSheet" href="lib3styles.css" type="text/css" />
> + <link rel="Start" href="documentation.html" type="text/html"
> + title="GNU C++ Standard Library" />
> + <link rel="Copyright" href="17_intro/license.html" type="text/html" />
> + </head>
> + <body>
> +
> + <h1 class="centered"><a name="top">C++ Standard Library ABI</a></h1>
> +
> + <p class="fineprint"><em>
> + The latest version of this document is always available at
> + <a href="http://gcc.gnu.org/onlinedocs/libstdc++/abi.html">
> + http://gcc.gnu.org/onlinedocs/libstdc++/abi.html</a>.
> + </em></p>
> +
> + <p><em>
> + To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++-v3 homepage</a>.
> + </em></p>
> +
> + <!-- ####################################################### -->
> + <hr />
> + <h3 class="left">
> + <a name="C++interface">The C++ interface</a>
> + </h3>
> +
> + <p> C++ applications often dependent on specific language support
> + routines, say for throwing exceptions, or catching exceptions, and
> + perhaps also dependent on features in the C++ Standard Library.
> + </p>
> +
> + <p> The C++ Standard Library has many include files, types defined in
> + those include files, specific named functions, and other behavior. The
> + text of these behaviors, as written in source include files, is called
> + the Application Programing Interface, or API.
> + </p>
> +
> + <p> Furthermore, C++ source that is compiled into object files is
> + transformed by the compiler: it arranges objects with specific
> + alignment and in a particular layout, mangling names according to a
> + well-defined algorithm, has specific arrangements for the support of
> + virtual functions, etc. These details are defined as the compiler
> + Application Binary Interface, or ABI. The GNU C++ compiler uses an
> + industry-standard C++ ABI starting with version 3. Details can be
> + found in the <a href="http://www.codesourcery.com/cxx-abi/abi.html">
> + ABI specification</a>.
> + </p>
> +
> + <p>
> + The GNU C++ compiler, g++, has a compiler command line option to
> + switch between various different C++ ABIs. This explicit version
> + switch is the flag <code> -fabi-version</code>. In addition, some
> + g++ command line options may change the ABI as a side-effect of
> + use. Such flags include <code>-fpack-struct</code> and
> + <code>-fno-exceptions</code>, but include others: see the complete
> + list in the GCC manual under the heading <a
> + href="http://gcc.gnu.org/onlinedocs/gcc/Code-Gen-Options.html#Code%20Gen%20Options">Options
> + for Code Generation Conventions</a>.
> + </p>
> +
> + <p> The configure options used when building a specific libstdc++
> + version may also impact the resulting library ABI. The available
> + configure options, and their impact on the library ABI, are documented
> + <a href="http://gcc.gnu.org/onlinedocs/libstdc++/configopts.html">
> + here</a>.
> + </p>
> +
> + <p> Putting all of these ideas together results in the C++ Standard
> + library ABI, which is the compilation of a given library API by a
> + given compiler ABI. In a nutshell:
> + </p>
> +
> + <code> library API + compiler ABI = library ABI</code>
> +
> + <p>
> + The library ABI is mostly of interest for end-users who have
> + unresolved symbols and are linking dynamically to the C++ Standard
> + library, and who thus must be careful to compile their application
> + with a compiler that is compatible with the available C++ Standard
> + library binary. In this case, compatible is defined with the equation
> + above: given an application compiled with a given compiler ABI and
> + library API, it will work correctly with a Standard C++ Library
> + created with the same constraints.
> + </p>
> +
> + <p>
> + To use a specific version of the C++ ABI, one must use a
> + corresponding GNU C++ toolchain (Ie, g++ and libstdc++) that
> + implements the C++ ABI in question.
> + </p>
> +
> + <h3 class="left">
> + <a name="ABI versioning">Versioning</a>
> + </h3>
> +
> + <p> The C++ interface has evolved throughout the history of the GNU
> + C++ toolchain. With each release, various details have been changed so
> + as to give distinct versions to the C++ interface.
> + </p>
> +
> + <h5 class="left">
> + <a name="goals">Goals of versioning</a>
> + </h5>
> +
> + <p>Extending existing, stable ABIs. Versioning gives subsequent stable
> + releases series libraries the ability to add new symbols and add
> + functionality, all the while retaining backwards compatibility with
> + the previous releases in the series. Note: the reverse is not true. It
> + is not possible to take binaries linked with the latest version of a
> + release series (if symbols have been added) and expect the initial
> + release of the series to remain link compatible.
> + </p>
> +
> + <p>Allows multiple, incompatible ABIs to coexist at the same time.
> + </p>
> +
> + <p>
> + </p>
> +
> + <h5 class="left">
> + <a name="details"> Version History </a>
> + </h5>
> + <p>
> + How can this complexity be managed? What does C++ versioning mean?
> + Because library and compiler changes often make binaries compiled
> + with one version of the GNU tools incompatible with binaries
> + compiled with other (either newer or older) versions of the same GNU
> + tools, specific techniques are used to make managing this complexity
> + easier.
> + </p>
> +
> + <p>
> + The following techniques are used:
> + </p>
> +
> + <ul>
> +
> + <li> <p>Release versioning on the libgcc_s.so binary. This is
> + implemented via file names and the ELF DT_SONAME mechanism (at least
> + on ELF systems).</p>
[...]
> + <li>gcc-3.4.0: libgcc_s.so.1</li>
on m68k-linux and hppa-linux this is either libgcc_s.so.1 (when
configuring --with-sjlj-exceptions) or libgcc_s.so.2.
Please can this documentation go to the 3.4 branch as well?
Thanks, Matthias