Add FAQ for DualABI incompatibility with gcc-4.9.

[EricCousineau-TRI]

This addresses #7467 per the discussion.

\cc @jamiesnape @jwnimmer-tri @naveenoid

---

This change is 

[EricCousineau-TRI]

+@jamiesnape for feature review, please.

---

Review status: 0 of 1 files reviewed at latest revision, all discussions resolved.

---

Comments from Reviewable

[jamiesnape]

---

Reviewed 1 of 1 files at r1.
Review status: all files reviewed at latest revision, 1 unresolved discussion.

---

doc/faq.rst, line 120 at r1 (raw file):

**Solution**: This is most likely due to an incompatibilty between the compiler used to produce Drake (e.g. ``clang-4``) and the compiler that CMake has selected (e.g. ``gcc-4.9``). Specifically, ``gcc-4.9`` or before does not tend to handle the DualABI well when linking against ``clang``-compiled code [#dual_abi]_. You may be able to use other functions, because only functions that return an ABI-dependent class (e.g. ``std::string``) are tagged with the ABI that they are using (since they cannot be distinguished in the function signature).

The fix is to change the compiler CMake is using. One way to do this is to set the ``CC`` and ``CXX`` environment variables to use the correct compiler, e.g. a later version of ``gcc``, or the same compiler that Bazel built the shared library with.

BTW Change "correct compiler" to "supported compiler" and link to the supported platforms matrix? Also maybe you could add a note to below that matrix saying that the binary packages are built with Clang 4.0 on Ubuntu 16.04 and Apple Clang 9.0 on macOS 10.13 and then link somewhere in the last part of sentence there (if the binary packages are being used).

---

Comments from Reviewable

[EricCousineau-TRI]

Review status: 0 of 3 files reviewed at latest revision, 1 unresolved discussion.

---

doc/faq.rst, line 120 at r1 (raw file):

Previously, jamiesnape (Jamie Snape) wrote…

BTW Change "correct compiler" to "supported compiler" and link to the supported platforms matrix? Also maybe you could add a note to below that matrix saying that the binary packages are built with Clang 4.0 on Ubuntu 16.04 and Apple Clang 9.0 on macOS 10.13 and then link somewhere in the last part of sentence there (if the binary packages are being used).

Done. How does this look?

---

Comments from Reviewable

[jamiesnape]

Reviewed 2 of 3 files at r2, 1 of 1 files at r3.
Review status: all files reviewed at latest revision, 1 unresolved discussion.

---

doc/faq.rst, line 120 at r1 (raw file):

Previously, EricCousineau-TRI wrote…

Done. How does this look?

Good.

---

Comments from Reviewable

[EricCousineau-TRI]

+@sammy-tri for platform review, please.

---

Review status: all files reviewed at latest revision, all discussions resolved.

---

Comments from Reviewable

[jamiesnape]

Review status: all files reviewed at latest revision, 1 unresolved discussion.

---

doc/developers.rst, line 100 at r3 (raw file):

---------------

The binary releases of Drake are built with Clang 4.0 on Ubuntu 16.04 and Apple Clang 9.0 on macOS 10.13.

Per offline conversation change Clang 4.0 to GCC 5.4.

---

Comments from Reviewable

[sammy-tri]

first pass (mostly) complete

---

Reviewed 2 of 3 files at r2.
Review status: all files reviewed at latest revision, 4 unresolved discussions.

---

doc/developers.rst, line 97 at r3 (raw file):

.. _binary-packages:

Binary Packages

I feel like this section might be premature as there are no binary packages available at this time.

---

doc/faq.rst, line 110 at r3 (raw file):

=======================================================================================================

**Symptom**: You have followed one of the options in the :ref:`installation_and_quick_start` instructions, and are writing a CMake project to use Drake.

I can't figure out what options this text refers to.

---

doc/faq.rst, line 120 at r3 (raw file):

**Solution**: This is most likely due to an incompatibilty between the compiler used to produce Drake (e.g. ``clang-4``) and the compiler that CMake has selected (e.g. ``gcc-4.9``). Specifically, ``gcc-4.9`` or before does not tend to handle the DualABI well when linking against ``clang``-compiled code [#dual_abi]_. You may be able to use other functions, because only functions that return an ABI-dependent class (e.g. ``std::string``) are tagged with the ABI that they are using (since they cannot be distinguished in the function signature).

The fix is to change the compiler CMake is using. One way to do this is to set the ``CC`` and ``CXX`` environment variables to use a supported compiler. For a list of supported compilers, see :ref:`supported-configurations`. If you are using pre-compiled binaries [#binary_install]_, please refer to the :ref:`binary-packages` for the compilers used.

I don't know where the reader would have gotten a pre-compiled binary.

---

Comments from Reviewable

[EricCousineau-TRI]

Review status: 2 of 3 files reviewed at latest revision, 4 unresolved discussions.

---

doc/developers.rst, line 97 at r3 (raw file):

Previously, sammy-tri (Sam Creasey) wrote…

I feel like this section might be premature as there are no binary packages available at this time.

We have them (see below), but they are not linked into the documentation.

@jamiesnape Should we include these links in the documentation? (So that way people don't have to dig in the issue? We can still say it's experimental at this point.)

---

doc/developers.rst, line 100 at r3 (raw file):

Previously, jamiesnape (Jamie Snape) wrote…

Per offline conversation change Clang 4.0 to GCC 5.4.

Done.

---

doc/faq.rst, line 110 at r3 (raw file):

Previously, sammy-tri (Sam Creasey) wrote…

I can't figure out what options this text refers to.

One of the three methods: Binary, Source, Docker.
Is there a rewording that would clarify this?

---

doc/faq.rst, line 120 at r3 (raw file):

Previously, sammy-tri (Sam Creasey) wrote…

I don't know where the reader would have gotten a pre-compiled binary.

These ones?
#1766 (comment)
(At least, the ones tested in drake-shambhala...)

---

Comments from Reviewable

[jamiesnape]

Review status: 2 of 3 files reviewed at latest revision, 4 unresolved discussions.

---

doc/developers.rst, line 97 at r3 (raw file):

Previously, EricCousineau-TRI wrote…

We have them (see below), but they are not linked into the documentation.

@jamiesnape Should we include these links in the documentation? (So that way people don't have to dig in the issue? We can still say it's experimental at this point.)

Sure.

---

Comments from Reviewable

[jamiesnape]

Review status: 2 of 3 files reviewed at latest revision, 4 unresolved discussions.

---

doc/developers.rst, line 100 at r3 (raw file):

Previously, EricCousineau-TRI wrote…

Done.

Thanks. The jobs on Jenkins have been updated also.

---

Comments from Reviewable

[sammy-tri]

Reviewed 1 of 1 files at r3, 1 of 1 files at r4.
Review status: all files reviewed at latest revision, 1 unresolved discussion.

---

doc/faq.rst, line 110 at r3 (raw file):

Previously, EricCousineau-TRI wrote…

One of the three methods: Binary, Source, Docker.
Is there a rewording that would clarify this?

I don't think any of those documents describes running the install step and then building a project which links to drake libraries which isn't built inside drake, but I could have missed it.

---

Comments from Reviewable

[EricCousineau-TRI]

Review status: 1 of 3 files reviewed at latest revision, 2 unresolved discussions.

---

doc/developers.rst, line 97 at r3 (raw file):

Previously, jamiesnape (Jamie Snape) wrote…

Sure.

Done.

---

doc/faq.rst, line 110 at r3 (raw file):

Previously, sammy-tri (Sam Creasey) wrote…

I don't think any of those documents describes running the install step and then building a project which links to drake libraries which isn't built inside drake, but I could have missed it.

Done. Added text regarding experimental CMake projects, linked to the drake_cmake_installed examples in Shambhala.

---

Comments from Reviewable

[sammy-tri]

Reviewed 2 of 2 files at r5.
Review status: all files reviewed at latest revision, all discussions resolved.

---

Comments from Reviewable

[sammy-tri]

---

Review status: all files reviewed at latest revision, all discussions resolved.

---

Comments from Reviewable

[sammy-tri]

+(status: curate commits before merging)

---

Review status: all files reviewed at latest revision, all discussions resolved, all commit checks successful.

---

Comments from Reviewable

[sammy-tri]

-(status: curate commits before merging) Sorry about that! I should have paid more attention to the contents of the individual commits.

---

Review status: all files reviewed at latest revision, all discussions resolved.

---

Comments from Reviewable