[www] 3.2 ABI Compatibility issues

[Andreas Jaeger <aj at suse dot de>]

Here's a new page documenting the ABI issues.  I currently mention
both GNU/Linux and BSD but so far have no comments regarding BSD.  If
there is anything that should be added for BSD, then please send me a
note and I'll add it.  Otherwise I remove the mention of BSD.

Thanks to both Jakub and Gerald for comments on the contents.

Gerald has approved the patch already but I wait with the commit for
further comments - and hopefully for an update regarding BSD.

Andreas

============================================================
Index: htdocs/gcc-3.2/changes.html
--- htdocs/gcc-3.2/changes.html	24 Jul 2002 07:21:02 -0000	1.25
+++ htdocs/gcc-3.2/changes.html	7 Aug 2002 08:30:30 -0000
@@ -31,7 +31,9 @@
 <h3>C++</h3>
 
   <ul>
-    <li>The C++ ABI now conforms to the V3 multi-vendor standard.</li>
+    <li>The C++ ABI now conforms to the V3 multi-vendor standard.  For
+    details on build  an ABI compliant compiler for GNU/Linux and BSD
+    systems, check the <a href="c++-abi.html">common C++ ABI page</a>.</li>
   </ul>
 
 
============================================================
Index: htdocs/gcc-3.2/c++-abi.html
--- htdocs/gcc-3.2/c++-abi.html	created
+++ htdocs/gcc-3.2/c++-abi.html	Wed Aug  7 09:56:09 2002	1.1
@@ -0,0 +1,74 @@
+<html>
+  <head>
+    <title>A Common C++ ABI for GNU/Linux and BSD</title>
+  </head>
+
+  <body>
+    <h1>A Common C++ ABI for GNU/Linux and BSD</h1>
+
+    <p>
+    The main point of the GCC 3.2 release is to have a relatively
+    stable and common C++ ABI for GNU/Linux and BSD usage.
+    Unfortunatly this means that GCC 3.2 is incompatible with GCC 3.0
+    and GCC 3.1 releases.</p>
+
+    <p>
+    But for real interoperability of C++ shared libraries and C++
+    programs, not only a GCC 3.2 based compiler has to be used but it
+    has to be built in a certain environment and with some specific
+    options.</p>
+
+    <p> We strongly advise all developers and distributors to follow
+    the guidelines given here for GNU/Linux systems.</p>
+
+   <h2>Configuring GCC</h2>
+    
+    <p>Configure GCC with these options:</p>
+    <pre>
+      --enable-threads=posix -enable-shared --enable-__cxa_atexit
+    </pre>
+    
+    <p>If you do not use these options, your files generated by GCC
+    will not be fully ABI compatible.</p>
+
+   <h2>Glibc</h2>
+
+    <p> On GNU/Linux systems use the GNU C Library version 2.2.5 or
+    newer.
+    </p>
+
+    <h2>Binutils</h2>
+
+    <p>
+    Use binutils 2.12.1 or any newer release.
+    </p>
+
+    <h2>Order of Builds</h2>
+
+   <p>Since GCC and glibc test for some features of binutils and
+   glibc, you have to build and install new versions (if needed) in
+   this order:</p>
+    <ol>
+      <li>New binutils version</li>
+      <li>New glibc version</li>
+      <li>GCC 3.2</li>
+    </ol>
+    <p>Especially, if you update binutils, you should rebuild glibc so
+    that glibc can take advantage of some new options of binutils.</p>
+
+    <h2>Caveat</h2>
+    
+    <p>Since GCC now implements a written ABI that is also implemented
+    by other compiler vendors, it might be that we encounter different
+    interpretations of the ABI by the vendors, bugs in the ABI or bugs
+    in the implementation of the ABI in different compilers.</p>
+
+    <p>
+    We have tried hard to have a stable ABI that is compatible with
+    future GCC releases.  At this point no promise can be made
+    that this release will be ABI compatible with all future GCC 3.x
+    versions but we will strive hard to keep GCC 3.3 compatible with
+    GCC 3.2.</p>
+
+  </body>
+</html>

-- 
 Andreas Jaeger
  SuSE Labs aj@suse.de
   private aj@arthur.inka.de
    http://www.suse.de/~aj