This is the mail archive of the gcc-patches@gcc.gnu.org mailing list for the GCC project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: [v3] abi docs, testsuite


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


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]