Merge pull request #7491 from EricCousineau-TRI/issue/7467

Add FAQ for DualABI incompatibility with gcc-4.9.

doc/developers.rst

@@ -92,6 +92,15 @@ and the combination of Bazel + Clang 3.9 is deprecated.
 macOS 10.13 ("High Sierra") MATLAB support is experimental and untested in continuous
 integration.
 
+.. _binary-packages:
+
+Binary Packages
+---------------
+
+The binary releases of Drake are built with GCC 5.4 on Ubuntu 16.04 and Apple Clang 9.0 on macOS 10.13.
+
+The links for these packages are listed in :ref:`binary-installation`.
+
 Code Review
 ===========
 

doc/faq.rst

@@ -13,7 +13,7 @@ Frequently Asked Questions
 Why Does Build Fail with "this rule is missing dependency declarations" on macOS?
 =================================================================================
 
-Symptom: After upgrading Xcode on macOS, you encounter an error similar to the
+**Symptom**: After upgrading Xcode on macOS, you encounter an error similar to the
 following::
 
     $ bazel build ...
@@ -26,7 +26,7 @@ following::
       '/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/
       Developer/SDKs/MacOSX10.12.sdk/usr/include/ctype.h'
 
-Solution: Install Xcode's command-line tools and reset the tools' path to be
+**Solution**: Install Xcode's command-line tools and reset the tools' path to be
 the default. To install Xcode's command-line tools::
 
     $ xcode-select --install
@@ -54,7 +54,7 @@ default, reset it to be the default by executing the following command::
 Why doesn't Drake Visualizer work in VMWare Fusion or Workstation?
 ==================================================================
 
-Symptom: The simulation runs and the visualization window appears, but no
+**Symptom**: The simulation runs and the visualization window appears, but no
 objects are actually drawn. This appeared to be due to display drivers and/or
 non support of hardware-accelerated rendering. To address this, go to
 ``Virtual Machine Settings``, and check the ``Accelerate 3D Graphics`` box under
@@ -65,7 +65,7 @@ Display settings; now the simulations draw properly.
 Why do OpenGL-based VTK targets run with ``bazel test`` sometimes fail on Linux?
 ================================================================================
 
-Symptom: While the binary works with ``bazel run``, when you run a test using ``bazel test``, such as::
+**Symptom**: While the binary works with ``bazel run``, when you run a test using ``bazel test``, such as::
 
     $ bazel test //drake/systems/sensors:rgbd_camera_test
 
@@ -83,7 +83,7 @@ you encounter a slew of errors from VTK / OpenGL::
     ERROR: In /vtk/Rendering/OpenGL2/vtkOpenGLRenderWindow.cxx, line 1858
     vtkXOpenGLRenderWindow (0x55880715b760): Hardware does not support the number of textures defined.
 
-Solution: The best workaround is to first mark the test as as `local <https://docs.bazel.build/versions/master/be/general.html#genrule.local>`_ in the ``BUILD`` file, either
+**Solution**: The best workaround is to first mark the test as as `local <https://docs.bazel.build/versions/master/be/general.html#genrule.local>`_ in the ``BUILD`` file, either
 with ``local = 1``, or ``tags = [.., "local"],``. Doing so will make the specific target run without sandboxing, such that it has an environment similar to that of ``bazel run``.
 
 As an example, in ``drake/systems/sensors/BUILD``::
@@ -101,3 +101,28 @@ If this does not work, then try running the test in Bazel without sandboxing::
 
 Please note that you can possibly add ``--spawn_strategy=standalone`` to your ``~/.bazelrc``, but be aware that this means your development machine
 may have a different environment than other development machines when running the test.
+
+.. _faq_gcc_4_9:
+
+Why do I get linker errors when I build a CMake project using Drake, but I can clearly see the symbols?
+=======================================================================================================
+
+**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.
+
+You look at a unittest that builds in Drake, run it, and it builds, runs, and passes. However, when you try to use some of that functionality in your CMake project, you get a linker error, such as::
+
+    undefined reference to `RigidBodyTree<double>::get_position_name(int) const'
+
+If you look at symbols in the Drake shared library (e.g. ``nm -C`` or ``objdump -TC`` with ``grep``), you see the signature ``RigidBodyTree<double>::get_position_name[abi:cxx11](int)``. However, if you look in the produced object code (which causes the linking to fail), you see ``RigidBodyTree<double>::get_position_name(int)``.
+
+**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.
+
+.. note::
+
+    Do not change the compiler using ``update-alternatives`` in Ubuntu, as this may affect your DKMS module compatiblity with the kernel (among other things) [#update_alt]_.
+
+.. [#dual_abi] https://stackoverflow.com/q/36159238/7829525
+.. [#binary_install] :ref:`binary-installation`
+.. [#update_alt] https://askubuntu.com/a/26500/692420

doc/from_binary.rst

@@ -1,3 +1,5 @@
+.. _binary-installation:
+
 ***********************************
 Binary installation (macOS, Ubuntu)
 ***********************************
@@ -9,13 +11,16 @@ Drake is currently undergoing a major renovation, with all of the core
 libraries moving into C++.  The examples will move and the existing APIs will
 change.
 
-We are actively working on a binary release of the new software, but are not
-quite finished.  See https://github.com/RobotLocomotion/drake/issues/1766 for
-details.
+There are `experimental binary packages <https://github.com/RobotLocomotion/drake/issues/1766#issuecomment-318955338>`_ of Drake available at:
 
-In the meantime, we suggest you :ref:`build from source <build_from_source>`
-instead.
+- https://s3.amazonaws.com/drake-packages/drake/nightly/drake-latest-xenial.tar.gz
+- :samp:`https://s3.amazonaws.com/drake-packages/drake/nightly/drake-{yyyymmdd}-xenial.tar.gz`.
+    - Example: https://s3.amazonaws.com/drake-packages/drake/nightly/drake-20170719-xenial.tar.gz
 
+Example usages of these binaries are shown in this `example CMake project <https://github.com/RobotLocomotion/drake-shambhala/tree/master/drake_cmake_installed>`_.
+For the compilers used to produce these releases, see :ref:`binary-packages`.
+If you are unsure of which approach to use, we suggest you :ref:`build from source <build_from_source>`
+instead.
 
 Using older (2015) releases
 ===========================