documenting C++ and libstdc++ ABI issues

documenting C++ and libstdc++ ABI issues

[Janis Johnson]

I'd like to formalize the documentation about C++ ABI conformance and
libstdc++ consistency.  I'll start with my notes from
http://gcc.gnu.org/ml/gcc/2002-08/msg01251.html and Benjamin's doc at
http://gcc.gnu.org/onlinedocs/libstdc++/abi.txt .  It will incorporate
pieces of the Interoperation section of the GCC Manual; that section is
currently under "Known Causes of Trouble" and looks horribly out of date
(example: "The GNU assembler (GAS) does not support PIC").

There should be a section in the GCC manual about ABI issues for C++
compiler and runtime support, and one in the libstdc++ manual about
libstdc++ issues.  Some of Benjamin's information would move to the
compiler documentation.

If someone is already working on this, or if such documentation already
exists and I just didn't find it, please let me know.

Janis Johnson
IBM Linux Technology Center

Re: documenting C++ and libstdc++ ABI issues

[Joseph S. Myers]

On Tue, 27 Aug 2002, Janis Johnson wrote:

> I'd like to formalize the documentation about C++ ABI conformance and
> libstdc++ consistency.  I'll start with my notes from
> http://gcc.gnu.org/ml/gcc/2002-08/msg01251.html and Benjamin's doc at
> http://gcc.gnu.org/onlinedocs/libstdc++/abi.txt .  It will incorporate
> pieces of the Interoperation section of the GCC Manual; that section is
> currently under "Known Causes of Trouble" and looks horribly out of date

There are at least two GCC manual sections relating to ABIs.  The
appropriate one to expand with non-C information (linking to appropriate
external documents) is probably that in the internals manual in
interface.texi.  As with that in trouble.texi, it suffers from documenting
information about old systems that few people use GCC on and not current
information about the ABIs for currently used systems.  (There may be
information in both those sections that relates *only* to systems for
which support has been removed; any such information should be removed.)

Explicit references to the external ABI specifications followed for C for
at least the current primary release platforms, and any known deviations
from those, and any extensions, would also be useful.

> (example: "The GNU assembler (GAS) does not support PIC").

It has been suggested this is still true for some a.out BSD systems (for
which the relevant support was never merged into GNU binutils).

-- 
Joseph S. Myers
jsm28@cam.ac.uk

Re: documenting C++ and libstdc++ ABI issues

[Janis Johnson]

On Tue, Aug 27, 2002 at 07:16:43PM +0100, Joseph S. Myers wrote:
> On Tue, 27 Aug 2002, Janis Johnson wrote:
> 
> > I'd like to formalize the documentation about C++ ABI conformance and
> > libstdc++ consistency.  I'll start with my notes from
> > http://gcc.gnu.org/ml/gcc/2002-08/msg01251.html and Benjamin's doc at
> > http://gcc.gnu.org/onlinedocs/libstdc++/abi.txt .  It will incorporate
> > pieces of the Interoperation section of the GCC Manual; that section is
> > currently under "Known Causes of Trouble" and looks horribly out of date
> 
> There are at least two GCC manual sections relating to ABIs.  The
> appropriate one to expand with non-C information (linking to appropriate
> external documents) is probably that in the internals manual in
> interface.texi.

This information is of interest to GCC users, not just developers, so
it should be in the GCC manual rather than the internals manual.

>  As with that in trouble.texi, it suffers from documenting
> information about old systems that few people use GCC on and not current
> information about the ABIs for currently used systems.  (There may be
> information in both those sections that relates *only* to systems for
> which support has been removed; any such information should be removed.)

What's a good way to get the appropriate people to review and update
this information?

> Explicit references to the external ABI specifications followed for C for
> at least the current primary release platforms, and any known deviations
> from those, and any extensions, would also be useful.

Good point.
> 
> > (example: "The GNU assembler (GAS) does not support PIC").
> 
> It has been suggested this is still true for some a.out BSD systems (for
> which the relevant support was never merged into GNU binutils).

Then the statement should be clarified when the section is reviewed.

Thanks for your input.

Janis

Re: documenting C++ and libstdc++ ABI issues

[Joseph S. Myers]

On Tue, 27 Aug 2002, Janis Johnson wrote:

> This information is of interest to GCC users, not just developers, so
> it should be in the GCC manual rather than the internals manual.

There's a need for user information about when ABI incompatibilities
affect linking code built with different compilers or compiler versions.  
But there's also a need for the technical documentation defining what the
ABI is, where this goes beyond the external standards (e.g., the ABI for
code using GCC extensions), and what the actual "3.2 ABI" is in cases
where it differs from the specification (whereas the user documentation
need only discuss what code is affected, not the detailed differences in
those cases).  I feel that technical documentation fits better in the
internals manual.

-- 
Joseph S. Myers
jsm28@cam.ac.uk

Re: documenting C++ and libstdc++ ABI issues

[Joe Buck]

> On Tue, 27 Aug 2002, Janis Johnson wrote:
> 
> > This information is of interest to GCC users, not just developers, so
> > it should be in the GCC manual rather than the internals manual.
> 
> There's a need for user information about when ABI incompatibilities
> affect linking code built with different compilers or compiler versions.  
> But there's also a need for the technical documentation defining what the
> ABI is, where this goes beyond the external standards (e.g., the ABI for
> code using GCC extensions), and what the actual "3.2 ABI" is in cases
> where it differs from the specification (whereas the user documentation
> need only discuss what code is affected, not the detailed differences in
> those cases).  I feel that technical documentation fits better in the
> internals manual.

Users will wish to know how to avoid code that tweaks one of the
incompatibilities, and such an explanation could appear in the user
manual.  Beyond that, I'd agree that the main guts go in internals.