compat.texi: Add info about C++ libraries.

2002-10-11  Janis Johnson  <janis187@us.ibm.com>

	* doc/compat.texi: Add info about C++ libraries.

From-SVN: r58074

1 files changed, 41 insertions, 0 deletions

diff --git a/gcc/doc/compat.texi b/gcc/doc/compat.texi
index 3e4ef89d..274368a 100644
--- a/gcc/doc/compat.texi
+++ b/gcc/doc/compat.texi
@@ -113,3 +113,44 @@ interpretations of the C++ ABI by different vendors, bugs in the ABI, or
 bugs in the implementation of the ABI in different compilers.
 GCC's @code{-Wabi} switch warns when G++ generates code that is
 probably not compatible with the C++ ABI@.
+
+The C++ library used with a C++ compiler includes the Standard C++
+Library, with functionality defined in the C++ Standard, plus language
+runtime support.  The runtime support is included in a C++ ABI, but there
+is no formal ABI for the Standard C++ Library.  Two implementations
+of that library are interoperable if one follows the de-facto ABI of the
+other and if they are both built with the same compiler, or with compilers
+that conform to the same ABI for C++ compiler and runtime support.
+
+When G++ and another C++ compiler conform to the same C++ ABI, but the
+implementations of the Standard C++ Library that they normally use do not
+follow the same ABI for the Standard C++ Library, object files built with
+those compilers can be used in the same program only if they use the same
+C++ library.  This requires specifying the location of the C++ library
+header files when invoking the compiler whose usual library is not being
+used.  The location of GCC's C++ header files depends on how the GCC
+build was configured, but can be seen by using the G++ @option{-v} option.
+With default configuration options for G++ 3.3 the compile line for a
+different C++ compiler needs to include
+
+@example
+    -I@var{gcc_install_directory}/include/c++/3.3
+@end example
+
+Similarly, compiling code with G++ that must use a C++ library other
+than the GNU C++ library requires specifying the location of the header
+files for that other library.
+
+The most straightforward way to link a program to use a particular
+C++ library is to use a C++ driver that specifies that C++ library by
+default.  The @command{g++} driver, for example, tells the linker where
+to find GCC's C++ library (@file{libstdc++}) plus the other libraries
+and startup files it needs, in the proper order.
+
+If a program must use a different C++ library and it's not possible
+to do the final link using a C++ driver that uses that library by default,
+it is necessary to tell @command{g++} the location and name of that
+library.  It might also be necessary to specify different startup files
+and other runtime support libraries, and to suppress the use of GCC's
+support libraries with one or more of the options @option{-nostdlib},
+@option{-nostartfiles}, and @option{-nodefaultlibs}.