Debugging Chromium on Windows

时间:2022-09-02 14:12:36

转自:https://www.chromium.org/developers/how-tos/debugging-on-windows

For Developers‎ > ‎How-Tos‎ > ‎

Debugging Chromium on Windows

This page has detailed information to help you debug Chromium on Windows.
 
Note: If you've never built or debugged Chromium on Windows, first read the Windows build instructions.

Before you start

Requirements

You can use Visual Studio's built-in debugger or WinDBG to debug Chromium. Note that if you are using goma to build, much of this will not work; see "Unable to set breakpoints in VS when building with goma on Windows".

Optional

So that you can continue to run release versions of the browser — and avoid incompatible profile changes — while you debug, you should use a different profile for your debug Chromium instance from the release build that you use. You can set the profile by modifying the command line used to launch Chromium from the debugger. To do this, go to the Debugging tab of the properties of the chrome project, and set the Command Arguments field to --user-data-dir=c:\tmp\my_debug_profile. (Replace c:\tmp\my_debug_profile with a directory of your choosing.) Another possibility, if you have lots of different checkouts, is to change the path of the shortcut you use for the release build so that it sets the profile.
 
Tools such as ProcessExplorer, Spy++/Winspector Spy, Inspect32, and FileMon may be of use when debugging different parts of Chromium.
 

Multi-process issues

Chromium can be challenging to debug because of its multi-process architecture. When you select Run in the debugger, only the main Browser process will be debugged. The code that actually renders web pages (the Renderer) and the plugins will be in separate processes that's not (yet!) being debugged.

There are a number of approaches to solving this problem.

Single-process mode

The easiest way to debug issues is to run Chromium in single-process mode. This will allow you to see the entire state of the program without extra work (although it will still have many threads). To use single-process mode, add the command-line flag --single-process to the Command Arguments field in the Debugging tab of the properties of the chrome project. This approach isn't perfect because some problems won't manifest themselves in this mode. Also, even in single-process mode, worker threads are spawned into new processes.

Tip: By default, when you load the project, Visual Studio may select Browser/browser.exe as the "startup project," and you will notice that chrome.exe is not bolded in the list of projects. If this is the case, then just clicking Debug > Start Debugging will start a different project, and ignore the command line flag you just provided. To change this, right-click the chrome.exe project and choose Set As Startup Project.

Using Image File Execution Options

Using Image File Execution Options (IFEO) will not work,  because CreateProcess() returns the handle to the debugger process instead of the intended child process. There are issues too with the sandbox.

Chrome Debug Log

Enable Chrome debug logging to a file by passing --enable-logging --v=1 command-line flags at startup. Debug builds place the chrome_debug.log file in the out\Debug directory. Release builds place the file in the top level of the user data Chromium app directory, which is OS-version-dependent. For more information, see logging and user data directory details.

Debugging with Visual Studio

Attaching to the renderer

You can also attach to the running child processes with the debugger. Select Tools > Attach to Process and click the chrome.exe process you want to attach to. You can now debug the two processes as if they were one.Use this macro or the vs-chromium plug-in to attach to the right processes.
When you are debugging multiple processes, open the Debug > Windows > Processes window to switch between them.
Sometimes you are debugging something that only happens on startup, and want to see the child process as soon as it starts. In this case, you can use the --renderer-startup-dialog command line flag to the browser.Important note: If you use this flag you also have to pass the --no-sandbox flag, since the sandbox will otherwise prevent the renderer from showing a startup dialog. The browser will pass this along to each renderer it starts, which will display a message box as soon as it starts. When the dialog appears, visit Tools > Attach to Process and attach to the process showing the Renderer startup dialog. Now you're debugging in the renderer.
 

Semi-automatically attaching the debugger to child processes

The following flags cause the processes to wait for 60 seconds in a busy loop for a debugger to attach to the process. Once either condition is true, it continues on; no exception is thrown. This is the only reliable way to debug an issue occurring on process startup with Visual Studio.

Usage

chrome.exe [--wait-for-debugger-children[=filter]] [--wait-for-debugger]

  • filter = plugin | renderer
  • --wait-for-debugger-children waits for a debugger in child processes for 60 seconds.
  • --wait-for-debugger waits for a debugger for 60 seconds.

It should be used with the .NET macro to help catch the processes. Alt-P does the job, too.

Symbol server

Save yourself some time and debug an official build! Setup your symbols:
  1. Menu Tools, Options
  2. Debugging, Symbols
  3. Add https://msdl.microsoft.com/download/symbols and https://chromium-browser-symsrv.commondatastorage.googleapis.com
  4. Setup a local cache in a empty directory on your computer, otherwise it'll be very slow.

Important note: release build debugging is much easier with WinDBG.

Don't step into trivial functions

Right click and select "Step Into Specific" when the current statement is on a line with multiple function calls.
Debugging Chromium on Windows
 

The debugger can be configured to automatically not step into functions based on regular expression:

  • For Visual Studio 2013:
    • Open C:\Program Files (x86)\Microsoft Visual Studio 12.0\Common7\Packages\Debugger\Visualizers\default.natstepfilter
  • For older versions of Visual Studio:
    • Find the registry location for your version of Visual Studio
      • Open regedit
      • Edit -> Find "StepOver"
        • (You only need to search Keys, and can match whole string only)
        • Different visual studio versions have different locations, e.g.:
          HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\VisualStudio\9.0\NativeDE\StepOver
        • Check if you have more than one, if so, pick the right version. ;) e.g. VS2008 == VS9.0
  • Add regular expressions of functions to not step into,
    • colons and angle brackets must be escaped with a \
    • You don't need to suffix =nostepinto, it's the default
    • Examples:
      • operator (new|delete).*   - operator new and delete
      • std\:\:.*                 - Skip everything in std.
      • WTF\:\:.*Ptr\<.*\>\:\:.*  - all methods on WebKit OwnPtr and variants, ... WTF::*Ptr<*>::*
  • Natstepfilter file or Registry is read at start of a debugging session with F5.
  • More info: Andy Pennel's Blogmicrosoft email thread

Debugging with WinDBG

WinDBG is a greatfree 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 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. Most of the time the one that you should use for Chromium is the 32-bit version.

Initial setup

Once you're started, you may wish to fix a few things:
  1. In menu FileSymbol File Path, type this where c:\code\symbols is your local symbol cache:

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

  2. Open a few windows from the View menu.
  3. Use FileOpen Executable to launch a process to debug.
  4. In the command prompt, you may want to use these commands:
    1. .asm no_code_bytes
  • disables display of opcodes
  • .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
  • If you want to automatically download source files that match a particular minidump, in the menu FileSource File Path set the value 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
  • In the menu ViewSource language file extensions..., add cc=C++ to have automatic source colors.
  • Dock the windows as you want them to be and save the workspace so that it is available in the future (File menu). 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.
  • 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, runwindbg.exe -IA
  • Register as the default just in time debugger: windbg.exe -I
  • Common commands

    • dt this->member_
      • Displays the data
    • x chrome*!*function_name
      • Finds a symbol.
    • .open -a [symbol address or complete symbol name found by using x]
      • Opens the source file containing the specified symbol. Pretty neat.
    • ?? [data name]
      • Quick evaluation of a C++ symbol (local variable, etc). You don't need to specify this-> for member variables but it's slower if you don't.
    • dv [/V]
      • Displays local variables
    • dd address
      • Displays the contents of memory at the given address (as doubles... dc, dw, dq etc)
    • dt -r1 type address
      • Displays an object of the given type stored at the given address, using 1 level of recursion.
    • !stl
      • Displays some stl structures (visualizer)
    • dt -n <type>
      • Displays a type forcing the name to the supplied type (when there are problematic characters in the name)
    • ~*n
      • Freezes all threads
    • ~4m
      • Thaws thread number 4
    • Ctrl-Shift-I
      • Sets the selected source line to be the next line to be executed
    • F5, Ctrl-Shift-F5, F9, F10, F11
      • Run, restart, toggle breakpoint, step over, step into.

    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

    • !analyze -v
      • Displays a basic crash analysis report.
    • .ecxr
      • Switch the context to the exception record.
    • dds address
      • Displays symbols following address (as in a stack or vtable)
    • k = address address address
      • Rebuilds a call stack assuming that address is a valid stack frame.
    • uf symbol
      • Unassembles a function showing source line number.
    • lm vmchr*
      • Lists verbose information about all modules with a name that starts with ch
    • ln address
      • Lists all symbols that match a given address (dedups a symbol).
    • .load wow64exts
      • On a 64-bit debugger, load the 32-bit extensions so that the current architecture can be switched
    • .effmach x86
      • Switches the current architecture to 32-bit.
    • .effmach x86; k = @ebp @ebp @ebp
      • Shows the 32-bit call stack from a 64-bit dump
    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.

    V8 and Chromium

    V8 supports many command-line flags that are useful for debugging. V8 command-line flags can be set via the Chromium command-line flag --js-flags; for instance:

    chrome.exe --js-flags="--trace_exception --heap_stats"

    Note that some V8 command-line flags exist only in the debug build of V8. For a list of all V8 flags try:

    chrome.exe --js-flags="--help"

    Graphical Debugging

    GPU Acceleration of rendering can be more easily debugged with tools. See:

    Debugging on another machine

    Sometimes it's useful to debug installation and execution on a machine other than your primary build box. To run the installer on said other machine, first build the mini_installer target on your main build machine (e.g., ninja -C out\Debug mini_installer). Next, on the debug machine:
    • Make the build machine's build volume available on the debug machine either by mounting it locally (e.g., Z:\) or by crafting a UNC path to it (e.g., \\builder\src)
    • Open up a command prompt and change to a local disk
    • Run src\tools\win\copy-installer.bat in the remote checkout by way of the mount (e.g., Z:\PATHTOCHECKOUT\src\...) or UNC path (e.g., \\builder\src\...). This will copy the installer, DLLs, and PDBs into your debug machine's C:\out or C:\build (depending on if you're rocking the component=shared_library build or not)
    • Run C:\out\Debug\mini_installer.exe with the flags of your choice to install Chrome. This can take some time, especially on a slow machine. Watch the Task Manager and wait until mini_installer.exe exits before trying to launch Chrome (by way of the shortcut(s) created by the installer)
    • For extra pleasure, add C:\out\Debug to your _NT_SYMBOL_PATH environment variable
    Consider reading the documentation at the top of copy-installer.bat to see how you can run it. It tries to be smart and copy the right things, but you may need to be explicit (e.g., "copy-installer.bat out Debug"). It is safe to re-run the script to copy only modified files (after a rebuild, for example).

    Miscellaneous

    • Application Verifier is a free tool from Microsoft. For the tool to run, you must disable the sandbox (--no-sandbox) and run all app-verified processes in a debugger. This means that you must run the renderer and plugin processes in a debugger or they will fail in mysterious ways. Use any of the methods mentioned above to attach to the renderer processes when they run.
    • To put a breakpoint on CreateFile(), add this break point:

    {,,kernel32.dll}_CreateFileW@28

      • {,,kernel32.dll}specifies the DLL (context operator).
      • _ prefix means extern "C".
      • @28 postfix means _stdcall with the stack pop at the end of the function. i.e. the number of arguments in BYTES.
    • You can use DebugView from SysInternals or sawbuck to view LOG() messages that normally goes to stderr on POSIX.

    Debugging Chromium on Windows的更多相关文章

    1. 在windows上编译chrome浏览器Building Chromium for Windows

      web端用webRTC实现的一对一视频,互动直播和会议.https://github.com/starrtc/android-demo Chromium requires Visual Studio ...

    2. Build Instructions &lpar;Windows&rpar; – The Chromium Projects

      转自:http://121.199.54.6/wordpress/?p=1156 原始地址:http://www.chromium.org/developers/how-tos/build-instr ...

    3. 记录windows下编译chromium,备忘

      编译windows下chromium,时间:20170619, 官方地址:https://chromium.googlesource.com/chromium/src/+/master/docs/wi ...

    4. Chromium Windows Build

      https://chromium.googlesource.com/chromium/src/+/refs/heads/main/docs/windows_build_instructions.md ...

    5. cef chromium 编译

      前言 目前客户端引用了cef sharp库来嵌入web页面 cef sharp是对cef (chromium embed framework)的c#封装 cef是对chromium内核的c++封装 什 ...

    6. Setup QT 5&period;5&period;1 &plus; OpenCV 3&period;0 &plus; Visual Studio 2013 on windows 10

      1. Install Visual studio 2013 community version which is free to use for personal usage. 2. Setup th ...

    7. 在64位windows 7上安装汇编调试工具debug&period;exe的方法

      最近我在研究汇编,书中介绍的调试工具还是基于WinXP 32bit时代中自带debug.exe进行调试,但是64bit的Windows XP.Vista.Win7.Win8都已经不自带这个工具了,网上 ...

    8. &period;NET对象与Windows句柄(三):句柄泄露实例分析

      在上篇文章.NET对象与Windows句柄(二):句柄分类和.NET句柄泄露的例子中,我们有一个句柄泄露的例子.例子中多次创建和Dispose了DataReceiver和DataAnalyzer对象, ...

    9. debugging books

      https://blogs.msdn.microsoft.com/debuggingtoolbox/2007/06/08/recommended-books-how-to-acquire-or-imp ...

    随机推荐

    1. eclipse hibernate 插件测试1

      今天先测试了hibernate tools 安装 在eclipse marketplace里面搜索 hibernate tools 就能找到 网上很多文章所说的使用 install new softw ...

    2. POD数据了解

      Plain old data (普通旧的数据); POD 是Plain Old Data的簡寫,是指一些系統的int, char, float.指標.array之類的資料型別,這應該蠻好想像的,就是C ...

    3. 给定任意一个字符串,使用 for in 语句来统计字符出现的个数

      //找出字符串中的数字 var str = 'haj123sdk54hask33dkhalsd879'; /*function findNum(str){ var arr = []; var tmp ...

    4. 基于Redis的消息订阅&sol;发布

      在工业生产设计中,我们往往需要实现一个基于消息订阅的模式,用来对非定时的的消息进行监听订阅. 这种设计模式在 总线设计模式中得到体现.微软以前的WCF中实现了服务总线 ServiceBus的设计模式. ...

    5. Vue语法学习第二课——指令

      指令,是指在Vue中,带有-v前缀的特殊特性 指令特性的值预期是单个JavaScript表达式(v-for例外) <p v-if="seen">看得到</p&gt ...

    6. 09-OpenLDAP加密传输配置

      OpenLDAP加密传输配置(CA服务器与openldap服务器异机) 阅读视图 环境准备 CA证书服务器搭建 OpenLDAP服务端与CA集成 OpenLDAP客户端配置 客户端测试验证 故障处理 ...

    7. java的acm输入输出格式&plus;大数语法

      1.类名称必须采用public class Main方式命名 2.多组输入,读取到文件尾 Scanner scan=new Scanner(System.in); while(scan.hasNext ...

    8. 转)GPL、BSD、MIT、Mozilla、Apache和LGPL的区别

      开源许可证GPL.BSD.MIT.Mozilla.Apache和LGPL的区别 以下是上述协议的简单介绍: BSD开源协议 BSD开源协议是一个给于使用者很大*的协议.基本上使用者可以”为所欲为”, ...

    9. 奇偶排序Odd-even sort

      又一个比较性质的排序,基本思路是奇数列排一趟序,偶数列排一趟序,再奇数排,再偶数排,直到全部有序 举例吧, 待排数组[6 2 4 1 5 9] 第一次比较奇数列,奇数列与它的邻居偶数列比较,如6和2比 ...

    10. Linux 入门记录:十六、Linux 多命令协作:管道及重定向

      一.多命令协作 在 Linux 系统当中,大多数命令都很简单,很少出现复杂功能的命令,每个命令往往只实现一个或多个很简单的功能.通过将不同功能的命令组合一起使用,可以实现某个复杂功能的. Linux ...