Make //tools/gdb easier to use

//tools/gdb was broken up into several different files that developers had to
source manually.  This change makes it so that all files get pulled in by
//tools/gdb/gdbinit, and also updates the documentation to point to a common
location for using gdbinit.

BUG=929992
R=thakis

Change-Id: Iea6c015a919b5615c0860e78ada246d7dbb5a278
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/1538564
Commit-Queue: Thomas Anderson <thomasanderson@chromium.org>
Reviewed-by: Nico Weber <thakis@chromium.org>
Auto-Submit: Thomas Anderson <thomasanderson@chromium.org>
Cr-Commit-Position: refs/heads/master@{#649401}

base/debug/debugger_posix.cc

@@ -203,9 +203,9 @@ void VerifyDebugger() {
          "able to find debug symbols, and pretty-printing of STL types may not "
          "work.  Please see debug instructions for using //tools/gdb/gdbinit:\n"
          "https://chromium.googlesource.com/chromium/src/+/master/docs/"
-         "linux_debugging.md#source-level-debug-with-fdebug_compilation_dir\n"
-         "To continue anyway, type 'continue' in gdb.  To ignore this check, "
-         "define an environment variable CHROMIUM_GDBINIT_SOURCED=1";
+         "gdbinit.md\n"
+         "To continue anyway, type 'continue' in gdb.  To always skip this "
+         "check, define an environment variable CHROMIUM_GDBINIT_SOURCED=1";
 #endif
 }
 

docs/gdbinit.md

@@ -0,0 +1,13 @@
+# Usage of tools/gdb/gdbinit
+
+Usage of Chromium's [gdbinit](../tools/gdb/gdbinit) is recommended when
+debugging with gdb on any platform. This is necessary for source-level debugging
+when `strip_absolute_paths_from_debug_symbols` or `use_custom_libcxx` are
+enabled (they're enabled by default), and also adds extra features like
+pretty-printing of custom Chromium types.
+
+To use, add the following to your `~/.gdbinit`
+
+```
+source /path/to/chromium/src/tools/gdb/gdbinit
+```

docs/graphical_debugging_aid_chromium_views.md

@@ -8,7 +8,8 @@ debugging. It consists of 4 components:
 1.  The function `views::PrintViewGraph()` (in the file
     `ui/views/debug_utils.h`),
 1.  a custom debugger command
-  - For GDB, use `tools/gdb/viewg.gdb`
+  - For GDB, see
+    [gdbinit](https://chromium.googlesource.com/chromium/src/+/master/docs/gdbinit.md),
   - For LLDB, use `tools/lldb/lldb_viewg.py`
   - For other debuggers, it should be relatively easy to adapt the
     above scripts.
@@ -22,8 +23,8 @@ To use the tool,
 
 1.  Make sure you have 'dot' installed (part of graphViz),
 1.  run gdb/lldb on your build and
-    1. For GDB `source tools/gdb/viewg.gdb` (this can be done automatically
-    in `.gdbinit`),
+    1. For GDB see
+    [gdbinit](https://chromium.googlesource.com/chromium/src/+/master/docs/gdbinit.md),
     1. For LLDB `command script import tools/lldb/lldb_viewg.py` (this can
     be done automatically in `.lldbinit`),
 1.  stop at any breakpoint inside class `View` (or any derived class), and

docs/linux_debugging.md

@@ -206,22 +206,10 @@ three) but you'll still need to use `--plugin-launcher` or another approach.
 
 ### Printing Chromium types
 
-gdb 7 lets us use Python to write pretty-printers for Chromium types. The
-directory `tools/gdb/` contains a Python gdb scripts useful for Chromium code.
-There is a similar script in `thrid_party/blink/tools/gdb`, which came from
-WebKit.
-
-To include these pretty-printers with your gdb, put the following into
-`~/.gdbinit`:
-
-```python
-python
-import sys
-sys.path.insert(0, "<path/to/chromium/src>/tools/gdb/")
-import gdb_chrome
-```
-
-This will import Blink pretty-printers as well.
+gdb 7 lets us use Python to write pretty-printers for Chromium types. See
+[gdbinit](https://chromium.googlesource.com/chromium/src/+/master/docs/gdbinit.md)
+to enable pretty-printing of Chromium types.  This will import Blink
+pretty-printers as well.
 
 Pretty printers for std types shouldn't be necessary in gdb 7, but they're
 provided here in case you're using an older gdb. Put the following into
@@ -276,13 +264,10 @@ your "gn args".
 ### Source level debug with -fdebug-compilation-dir
 
 When `strip_absolute_paths_from_debug_symbols` is enabled (which is the
-default) you need to add following command to your `~/.gdbinit` for source
-level debugging to load customized [gdbinit](../tools/gdb/gdbinit) or copy the
-content of the file to your `~/.gdbinit`.
-
-```
-source path/to/chromium/src/tools/gdb/gdbinit
-```
+default), gdb may not be able to find debug files, making source-level debugging
+impossible. See
+[gdbinit](https://chromium.googlesource.com/chromium/src/+/master/docs/gdbinit.md)
+to configure gdb to be able to find debug files.
 
 ## Core files
 

tools/gdb/gdb_chrome.py

@@ -39,7 +39,7 @@ sys.path.insert(
 try:
   import blink
 finally:
-  sys.path.pop(0)
+  sys.path.pop(1)
 
 # When debugging this module, set the below variable to True, and then use
 #   (gdb) python del sys.modules['gdb_chrome']

tools/gdb/gdbinit

@@ -1,5 +1,6 @@
-# This is gdbinit for source level debugging with -fdebug-compilation-dir
-# compile option or when building with libc++.
+# Copyright 2018 The Chromium Authors. All rights reserved.
+# Use of this source code is governed by a BSD-style license that can be
+# found in the LICENSE file.
 
 python
 
@@ -7,9 +8,14 @@ import os
 import subprocess
 import sys
 
+compile_dirs = set()
+
+
 def get_current_debug_file_directories():
   dir = gdb.execute("show debug-file-directory", to_string=True)
-  dir = dir[len('The directory where separate debug symbols are searched for is "'):-len('".')-1]
+  dir = dir[
+      len('The directory where separate debug symbols are searched for is "'
+         ):-len('".') - 1]
   return set(dir.split(":"))
 
 
@@ -18,36 +24,37 @@ def add_debug_file_directory(dir):
   # `show debug-file-directory` and `set debug-file-directory <directories>`.
   current_dirs = get_current_debug_file_directories()
   current_dirs.add(dir)
-  gdb.execute("set debug-file-directory %s" % ":".join(current_dirs),
-              to_string=True)
+  gdb.execute(
+      "set debug-file-directory %s" % ":".join(current_dirs), to_string=True)
 
 
-libcxx_pretty_printers_loaded = False
-def load_libcxx_pretty_printers(compile_dir):
-  global libcxx_pretty_printers_loaded
-  if libcxx_pretty_printers_loaded:
-    return
-  git = subprocess.Popen(
-      ['git', '-C', compile_dir, 'rev-parse', '--show-toplevel'],
-      stdout=subprocess.PIPE,
-      stderr=subprocess.PIPE)
-  src_dir, _ = git.communicate()
-  if git.returncode:
-    return
-  libcxx_pretty_printers = os.path.join(str(src_dir).rstrip(), 'third_party',
+def load_libcxx_pretty_printers(src_dir):
+  libcxx_pretty_printers = os.path.join(src_dir, 'third_party',
                                         'libcxx-pretty-printers')
   if not os.path.isdir(libcxx_pretty_printers):
     return
   sys.path.insert(1, libcxx_pretty_printers)
   from printers import register_libcxx_printers
   register_libcxx_printers(None)
-  libcxx_pretty_printers_loaded = True
+
+
+def load_gdb_chrome(src_dir):
+  tools_gdb = os.path.join(src_dir, 'tools', 'gdb')
+
+  sys.path.insert(1, tools_gdb)
+  import gdb_chrome
+
+  gdb.execute('source %s' % os.path.join(tools_gdb, 'viewg.gdb'))
 
 
 def newobj_handler(event):
+  global compile_dirs
   compile_dir = os.path.dirname(event.new_objfile.filename)
   if not compile_dir:
     return
+  if compile_dir in compile_dirs:
+    return
+  compile_dirs.add(compile_dir)
 
   # Add source path
   gdb.execute("dir %s" % compile_dir)
@@ -57,7 +64,18 @@ def newobj_handler(event):
   # https://crbug.com/603286#c35
   add_debug_file_directory(compile_dir)
 
-  load_libcxx_pretty_printers(compile_dir)
+  git = subprocess.Popen(
+      ['git', '-C', compile_dir, 'rev-parse', '--show-toplevel'],
+      stdout=subprocess.PIPE,
+      stderr=subprocess.PIPE)
+  src_dir, _ = git.communicate()
+  if git.returncode:
+    return
+  src_dir = str(src_dir).rstrip()
+
+  load_libcxx_pretty_printers(src_dir)
+
+  load_gdb_chrome(src_dir)
 
 
 # Event hook for newly loaded objfiles.

tools/gdb/viewg.gdb

@@ -9,7 +9,7 @@
 # For more info see
 # chromium/src/+/HEAD/docs/graphical_debugging_aid_chromium_views.md
 #
-# To make this command available, add the following to your ~/.lldbinit:
+# To make this command available, add the following to your ~/.gdbinit:
 # source {Path to SRC Root}/tools/gdbviewg.gdb
 #
 # Usage: type `viewg` at the GDB prompt, given the conditions above.