Add an OS X debugging workaround.

See bazelbuild/bazel#2537

drake/doc/bazel.rst

@@ -103,6 +103,20 @@ Cheat sheet for operating on specific portions of the project::
   prerequisite libraries are also compiled and linked in ``dbg`` mode.
 - For the definitions of the "``--config``" options see ``drake-distro/tools/bazel.rc``.
 
+Debugging on OS X
+-----------------
+
+On OS X, DWARF debug symbols are emitted to a ``.dSYM`` file. The Bazel
+``cc_binary`` and ``cc_test`` rules do not natively generate or expose this
+file, so we have implemented a workaround in Drake, ``--config=apple_debug``.
+This config turns off sandboxing, which allows a ``genrule`` to access the
+``.o`` files and process them into a ``.dSYM``.  Use as follows::
+
+  bazel build --config=apple_debug drake/path/to/my:binary_or_test_dsym
+  lldb ./bazel_bin/drake/path/to/my/binary_or_test
+
+For more information, see https://github.com/bazelbuild/bazel/issues/2537.
+
 Updating BUILD files
 ====================
 

tools/BUILD

@@ -203,3 +203,12 @@ config_setting(
         "cpu": "k8",
     },
 )
+
+config_setting(
+    name = "apple_debug",
+    values = {
+        "compilation_mode": "dbg",
+        "cpu": "darwin",
+    },
+)
+

tools/bazel.rc

@@ -77,6 +77,12 @@ build --deleted_packages=externals/snopt,externals/snopt/cppsrc,externals/snopt/
 test:cpplint --build_tests_only
 test:cpplint --test_tag_filters=cpplint
 
+### Debug symbols on OS X. ###
+# See https://github.com/bazelbuild/bazel/issues/2537
+build:apple_debug --spawn_strategy=standalone
+build:apple_debug --genrule_strategy=standalone
+build:apple_debug --compilation_mode=dbg
+
 ### Kcov coverage build. ###
 build:kcov --copt -g
 test:kcov --spawn_strategy=standalone

tools/drake.bzl

@@ -29,6 +29,14 @@ def _platform_copts(rule_copts):
       "//conditions:default": rule_copts,
   })
 
+def _dsym_command(name):
+  """Returns the command to produce .dSYM on OS X, or a no-op on Linux."""
+  return select({
+      "//tools:apple_debug":
+          "dsymutil -f $(location :" + name + ") -o $@ 2> /dev/null",
+      "//conditions:default": "touch $@",
+  })
+
 def drake_cc_library(
         name,
         hdrs=None,
@@ -59,6 +67,7 @@ def drake_cc_binary(
         deps=None,
         copts=[],
         linkstatic=1,
+        testonly=0,
         **kwargs):
     """Creates a rule to declare a C++ binary.
 
@@ -71,9 +80,22 @@ def drake_cc_binary(
         srcs=srcs,
         deps=deps,
         copts=_platform_copts(copts),
+        testonly=testonly,
         linkstatic=linkstatic,
         **kwargs)
 
+    # Also generate the OS X debug symbol file for this binary.
+    native.genrule(
+        name=name + "_dsym",
+        srcs=[":" + name],
+        outs=[name + ".dSYM"],
+        output_to_bindir=1,
+        testonly=testonly,
+        tags=["dsym"],
+        visibility=["//visibility:private"],
+        cmd=_dsym_command(name),
+    )
+
 def drake_cc_test(
         name,
         size=None,
@@ -106,6 +128,18 @@ def drake_cc_test(
         copts=_platform_copts(copts),
         **kwargs)
 
+    # Also generate the OS X debug symbol file for this test.
+    native.genrule(
+        name=name + "_dsym",
+        srcs=[":" + name],
+        outs=[name + ".dSYM"],
+        output_to_bindir=1,
+        testonly=1,
+        tags=["dsym"],
+        visibility=["//visibility:private"],
+        cmd=_dsym_command(name),
+    )
+
 def drake_cc_googletest(
         name,
         deps=None,