Blink‎ > ‎

Getting Started with Blink Debugging


While many of the tools and tips on this page can be used for it, this page focuses on debugging Blink outside the context of the Layout Tests. For more Layout Test specific instructions, see this page. For more general Chromium debugging info, see the respective pages for debugging on Windows, Mac, and Linux.


Getting Started

There are two main ways to get into blink: via debugging the chromium binary itself or content_shell. For most purposes of exclusive Blink debugging, the later is the recommended option because it drastically reduces size and complexity. This means building content_shell, which should be as simple as making it the build target for your build method of choice. This should stick a content_shell binary in your out/Debug or out/Release directory, depending on your build type.

content_shell itself takes as an argument the HTML file you wish to run Blink on. Furthermore, one of the simplest types of debugging you might want to do is to see the basic page structure after a page load (this internal structure in Blink is called the Render Tree, not to be confused with the DOM Tree or the Line Box Tree). You can do this with a simple command line option of --dump-render-tree. Thus, one of your simplest debugging tools, seeing the page structure after a page load, might look something like:
content_shell --dump-render-tree test.html

Starting the Debugger

Debugging on Linux is generally done with GDB, so we will assume that's what you are using here. Not surprisingly, you will almost always want to compile Blink in debug mode to get all the symbols and tools you will need.

Assuming you are using content_shell, you will probably want to run it in single process mode, unless, of course, you are dealing with threading issues. This will greatly simplify your setup and speed up your debugging process. Doing this is as simple as starting content_shell with the --single-process flag.

A common GDB command to get everything started is:
gdb --args content_shell --single-process test.html
If you can't use --single-process  you can use --renderer-startup-dialog instead. Simply run content_shell with the normal flags you pass it as well as --renderer-startup-dialog  The renderer will start in a paused state and allow you to attach a debugger before continuing.

General Useful Debugging Tools

There are some key functions built into objects once you've reach a breakpoint inside Blink. For the examples here, we'll assume you're using GDB on Linux. Two of the key ones are showRenderTreeForThis on RenderObjects and showTreeForThis on both RenderObjects and Nodes. These will, during a debug breakpoint, provide the Render Tree and DOM Tree as strings, respectively, for the provided objects. This is incredibly useful for showing the trees midway during execution to try and identify points when things change. You can use the GDB command print to display them. Assuming a local variable child in scope that's a RenderObject, the following will print the Render Tree:
(gdb) print child->showRenderTreeForThis()

Printing back trace

Make ASSERT print symbols

Run Chrome with --no-sandbox. You'll see Chromium's back trace for SEGV.

Use Chromium's StackTrace

#include <base/debug/stack_trace.h>
base::debug::StackTrace st;

and run Chrome with --no-sandbox command line option.

Make BACKTRACE() print symbols without Chromium code

Use component build mode

$ build/gyp_chromium -D"component=shared_library"

and then BACKTRACE(), ASSERT(), etc. will print (a few) symbols.