Debugging Chromium

This document provides a high-level overview of debugging the Chromium browser and its child processes. For more detailed and platform-specific instructions, please see the links at the end of this guide.

Getting Started: Attaching to Processes

Chromium is a multi-process application. The first step in debugging is often identifying and attaching to the correct process.

• Browser Process: This is the main process. You can start it directly in a debugger (e.g., gdb --args out/Default/chrome).
• Renderer, GPU, and Utility Processes: These are child processes launched by the browser. To debug them from startup, you need to use special command-line flags.

Useful Command-Line Flags for Debugging

Pass these to the chrome executable to alter its behavior for debugging.

• --wait-for-debugger
  • Pauses the child process (renderer, GPU, etc.) on startup until a debugger is attached. This is the most reliable way to debug child process initialization.
• --renderer-cmd-prefix='xterm -e gdb --args'
  • Launches new renderer processes inside an xterm with gdb attached. This is a common and useful debugging flag on Linux.
• --utility-cmd-prefix='xterm -e gdb --args'
  • Same as above, but for utility processes.
• --no-sandbox
  • Disables the security sandbox in all processes. This can make it easier to attach a debugger, but be aware of the security implications.
• --single-process
  • Runs the renderer and browser in the same process. Note: This is not a realistic representation of how Chrome runs and can mask or create bugs that don't exist in multi-process mode. Use with caution.
• --enable-logging --v=1
  • Enables verbose logging, which can be very helpful for understanding what's happening. Increase the v value for more verbosity.

Finding the Right Process

When Chrome is already running, you can use its built-in Task Manager to find the process you want to debug.

• Open Task Manager: Shift+Esc (or More Tools > Task Manager in the menu).
• Get Process ID (PID): Right-click on the table header and enable the "Process ID" column. You can then use this PID to attach your debugger (gdb -p <pid>).

Platform-Specific Guides

For detailed instructions on setting up and using a debugger on your specific platform, please refer to the following guides:

• Debugging on Linux
• Debugging on Windows
• Debugging on macOS
• Debugging on ChromeOS
• Debugging on Android
• Debugging on Fuchsia

Other Useful Debugging Resources

• Debugging GPU-related code
• Debugging memory issues
• Debugging with crash keys