From 3d482da77019001f4053720faf70b442df95f7c6 Mon Sep 17 00:00:00 2001
From: David German <dgerman@macsim.cam2.tri.global>
Date: Mon, 27 Feb 2017 11:36:43 -0500
Subject: [PATCH] Add an OS X debugging workaround.

This generates .dSYM files for cc_binary and cc_test rules.

See https://github.com/bazelbuild/bazel/issues/2537
---
 drake/doc/bazel.rst | 14 ++++++++++++++
 tools/BUILD         |  9 +++++++++
 tools/bazel.rc      | 11 +++++++++++
 tools/drake.bzl     | 34 ++++++++++++++++++++++++++++++++++
 4 files changed, 68 insertions(+)

diff --git a/drake/doc/bazel.rst b/drake/doc/bazel.rst
index 753b1d736302..d3c976bd429f 100644
--- a/drake/doc/bazel.rst
+++ b/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
 ====================
 
diff --git a/tools/BUILD b/tools/BUILD
index 6a642a6c16bf..9285fd9e107f 100644
--- a/tools/BUILD
+++ b/tools/BUILD
@@ -203,3 +203,12 @@ config_setting(
         "cpu": "k8",
     },
 )
+
+config_setting(
+    name = "apple_debug",
+    values = {
+        "compilation_mode": "dbg",
+        "cpu": "darwin",
+    },
+)
+
diff --git a/tools/bazel.rc b/tools/bazel.rc
index 24a56b6ef4fc..646e72ce17f1 100644
--- a/tools/bazel.rc
+++ b/tools/bazel.rc
@@ -77,6 +77,17 @@ 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
+
+# We don't actually use APPLE_DEBUG in code. It's just here to invalidate any
+# sandboxed .o files that might be in cache if a developer tried to build
+# with --compilation_mode=dbg instead of --config=apple_debug.
+build:apple_debug --copt="-DAPPLE_DEBUG"
+
 ### Kcov coverage build. ###
 build:kcov --copt -g
 test:kcov --spawn_strategy=standalone
diff --git a/tools/drake.bzl b/tools/drake.bzl
index 87ff27077ff8..aa38c6538a53 100644
--- a/tools/drake.bzl
+++ b/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,