the Chromium logo

The Chromium Projects
For Developers > How-Tos > Debugging Chromium on Windows >

WinDbg help

WinDbg is a great, free tool. It is more powerful than Visual Studio's built-in debugger, but is harder to use (kind of like gdb on Linux). You can retrieve the latest SDK version from Microsoft's web site. You should end up with two versions of the tool: the 32-bit debugger and the 64-bit debugger. If you already have it installed or if you are using the packaged Chromium toolchain (which includes windbg) then you can launch it using tools\win\windbg32.bat or tools\win\windbg64.bat. These batch files find and run the appropriate version, wherever it is.

You can also install WinDbg Preview, the new/preview version of WinDbg, from the Microsoft Store or this link. Discussion of various issues around getting this version can be found here. WinDbg Preview is being more actively developed and has a friendlier out-of-box experience so it is probably the best choice for new WinDbg users. The executable name for WinDbg Preview is WinDbgX.exe so substitute that for windbg in examples below. WinDbgX.exe should automatically be in your path once you install it.

Initial setup

Once you're started, you may wish to fix a few things. If you have run WinDbg before and saved any workspaces, you may wish to start with a clean slate by deleting the key HKCU\Software\Microsoft\Windbg using your favorite registry editor.

  1. Set the environment variable _NT_SYMBOL_PATH, as per Symbol path for Windows debuggers (e.g., File -> Symbol Search Path), to: https://chromium-browser-symsrv.commondatastorage.googleapis.com****SRV*c:\code\symbols*https://msdl.microsoft.com/download/symbols;SRV*c:\code\symbols*
  2. Configure WinDbg to use a sensible window layout by navigating explorer to "C:\Program Files (x86)\Windows Kits\10\Debuggers\x64\themes" and double-clicking on standard.reg (not needed with WinDbg Preview).
  3. Launch windbg.exe and:
    1. In the menu File, Source File Path..., set the path to srv*.
      • If you have a local checkout of the source, you can just point Source Path to the root of your code (src). Multiple paths are separated by semicolons.
      • If you want to download the individual source files to a given directory, add the destination to the path like so: srv*c:\path\to\downloaded\sources;c:\my\checkout\src
    2. In the menu View, Source language file extensions..., add cc=C++ to have automatic source colors.
    3. Optionally, customize the window layout as desired via the View menu, and dock the windows as you want them to be. Note that the UI allows multiple "Docks" and each Dock can have multiple tiled panels in it, and each panel can have multiple tabbed windows. You may want to have source files to be tabbed on the same panel, and visible at the same time as local variables and the stack and command windows. It is useful to realize that by default windbg creates a workspace per debugged executable or minidump, so each target can have its own configuration. The "default" workspace is applied to new targets.
    4. Optionally, run additional customization commands such as:
      1. .asm no_code_bytes
        • disables display of opcodes
      2. .prompt_allow -sym -dis -ea -reg -src
        • Disables display of symbol for the current instruction, disassembled instructions, effective address of current instruction, current state of registers and source line for the current instruction
      3. .srcfix
        • Enables source server. This tells the debugger to use information in the Chrome PDBs to download the correct version of all necessary source files.
    5. Use File, Save Workspace to make this new configuration the default for all future execution.
    6. Exit windbg.
  4. In Windows Explorer, associate .dmp extension with windbg.exe. You may have to manually add -z to the open command like so: "...\windbg.exe" -z "%1" to make this work properly. Alternatively, run windbg.exe -IA
  5. Register as the default just in time debugger: windbg.exe -I

To set your symbol and source environment variables permanently, you can run the following commands:

setx _NT_SYMBOL_PATH SRV*c:\code\symbols*https://msdl.microsoft.com/download/symbols;SRV*c:\code\symbols*https://chromium-browser-symsrv.commondatastorage.googleapis.com

setx _NT_SOURCE_PATH SRV*c:\code\source;c:\my\checkout\src

Common commands

One of the major benefits of WinDbg for debugging Chromium is its ability to automatically debug child processes. This allows you to skip all the complicated instructions above. The easiest way to enable this is to check "Debug child processes also" in the "Open Executable" dialog box when you start debugging or start "windbg.exe -o". NOTE that on 64-bit Windows you may need to use the 64-bit WinDbg for this to work. You can switch dynamically the setting on and off at will with the .childdbg 1|0 command, to follow a particular renderer creation. You can also attach to a running process (F6) and even detach without crashing the process (.detach)

Common commands when working with a crash

For more info, see this example of working with a crash dump, consult the program help (really, it's exhaustive!), see Common windbg commands or use your favorite search engine.

Random handy hints

To set attach to child processes, and also skip the first breakpoint and the extra breakpoint on process exit (this gives you a pretty responsive Chrome you can debug):

sxn ibp

sxn epr

.childdbg 1

g

You can also get this effect by using the -g -G -o options when launching windbg, as in:

windbg -g -G -o chrome.exe

To automatically attach to processes you want to run over and over with complex command lines, just attach WinDbg to your command prompt and then .childdbg 1 the command prompt - any processes launched from there will automatically be debugged. H/T pennymac@

To set a breakpoint in the current process you can use this module/function syntax, among others:

bp msvcrt!invalid_parameter

To apply this to future processes that are created (assuming child process debugging is enabled) you can use this syntax, which says to run the bp command whenever a new process is created:

sxe -c "bp msvcrt!invalid_parameter" cpr

If you want a chance to do this when you first launch the browser process then you need to launch it without -g (so that the first breakpoint will be hit). You will probably then want to disable the "Create process" breakpoint and "Initial breakpoint" with these commands:

sxn ibp; sxn epr;

These are equivalent to going to Debug-> Event Filters and setting "Create process" and "Initial breakpoint" to "Ignore".

Always use --user-data-dir when starting Chrome built with branding=Chrome or else you're going to have a bad time.

Resources