docs: Document binary compatibility issue due to bug in gcc

[tstellar]

Summary

Reported in PR33161.

[vsk]

Could you add links to this document in index.rst and UsersManual.rst?

docs/BinaryCompatibilityWithOtherCompilers.rst

40

This link is still showing up as 'insecure'. Mind using this?: https://bugs.llvm.org/show_bug.cgi?id=33161

[tstellar]

Add links to index.rst and UsersManual.rst, and fix link to bug.

docs/BinaryCompatibilityWithOtherCompilers.rst

+=========================================
+Binary compatibility with other compilers
+=========================================
+
+Introduction
+============
+
+This document describes some of the known binary compatibility problems
+when mixing object files built by clang with object files built by
+other compilers.
+
+If you run into a compatibility issue, please file a bug at bugs.llvm.org.
+
+gcc C++ ABI bug with variadic templates
+=======================================
+
+Older versions of gcc incorrectly mangle variadic class/function templates,
+which can lead to undefined symbol errors when linking gcc built objects
+with clang built objects.
+
+gcc does emit the correct symbol name as an alias for the incorrect one,
+so libraries built by gcc are not affected by this bug.  You can only
+hit this bug if you have a library built by clang and you try to link
+against it with a gcc built object that uses a variadic class/function
+template from the library.
+
+workarounds:
+^^^^^^^^^^^
+
+* Use gcc 5.1.0 or newer.
+* Pass the -fabi-version=6 option to gcc when using versions < 5.1.0.
+
+gcc bug report:
+^^^^^^^^^^^^^^^
+https://gcc.gnu.org/bugzilla/show_bug.cgi?id=51322
+
+llvm bug report:
+^^^^^^^^^^^^^^^^
+https://bugs.llvm.org/show_bug.cgi?id=33161

docs/UsersManual.rst

 
 .. option:: -foperator-arrow-depth=N
 
   Sets the limit for iterative calls to 'operator->' functions to N.  The
   default is 256.
 
 .. _objc:
 
+:doc:`BinaryCompatibilityWithOtherCompilers`
+--------------------------------------------
+
 Objective-C Language Features
 =============================
 
 .. _objcxx:
 
 Objective-C++ Language Features
 ===============================
 

docs/index.rst

.. toctree::
    SanitizerSpecialCaseList
    ControlFlowIntegrity
    LTOVisibility
    SafeStack
    SourceBasedCodeCoverage
    Modules
    MSVCCompatibility
    ThinLTO
+   BinaryCompatibilityWithOtherCompilers
    CommandGuide/index
    FAQ
 
 Using Clang as a Library
 ========================
 
 .. toctree::
    :maxdepth: 1