Debugging Firefox using Visual Studio .NET 2005

Introduction

I wrote previously on how to build Firefox trunk on Windows using Visual Studio .NET 2005, and my next task was to use the VS debugger to try and better understand how certain things work. I'm primarily interested in how events move from the OS through Firefox's event system, eventually becoming DOM events. However, you can use these steps to investigate whatever interests you.

As I did before, I continue to post these with the disclaimer that you are advised to consult the official documentation before reading/trying what I've written. You can find an official FAQ on debugging Mozilla on Win32 here.

Firefox, meet Visual Studio. Visual Studio, meet Firefox.

  1. The first step is to open VS.NET 2005 and then do File > Open > Project/Solution.... This will start the Open Dialog, and you should navigate to firefox.exe located in the dist\bin directory within the objdir you specified in .mozconfig (e.g., mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/firefox-objdir). [NOTE: for me that's C:\proj\mozilla\firefox-objdir\dist\bin\firefox.exe]
  2. File > Open > Firefox.exe
  3. This will create a Solution File (.sln) in the same directory as firefox.exe and give you the following in Solution Explorer [NOTE: we'll manually load source files in a moment, so don't worry that you don't see any source files yet]:
  4. Solution Explorer
  5. Now you need to right-click firefox.exe in Solution Explorer and add MOZ_NO_REMOTE=1 to the list of Environment variables. This allows a second Firefox to start along side one that may already be running (e.g., the one you're reading this document in).
  6. Build Properties
  7. At this point you are ready to set a breakpoint in a source file so you can stop Firefox and inspect it running at the appropriate point. Open a source file [File > Open > File...], for example, C:\proj\mozilla\widget\windows\nsWindow.cpp. Then locate a suitable location for your breakpoint(s) and click to the left of the line numbers in the gray selection border--you should see a filled red circle:
  8. Setting Breakpoint
  9. Finally, you can run Firefox from within VS.NET by pressing F5 or by clicking Debug > Start Debugging. This will cause a console window to open with lots of messages related to debugging within the code. Eventually, you should get dropped into the debugger at the location of your breakpoint (NOTE: if you pick a line that doesn't get called, this won't happen, so choose wisely!).
  10. Now you can do all the magic that's possible with the VS.NET debugger. In the example below you can see that the program has been halted at line 4346--my breakpoint. I've advanced beyond that manually using the F11 key to line 4350. As you step through the code, VS.NET will automatically load the other source files it needs to show you what's happening. Notice the Call Stack window, which will help orient you as you learn the program's flow. Also, notice how you can inspect variables at run-time using the Autos window. As you can see, the mouse has been moved (that's what caused the WM_MOUSEMOVE message) and the X and Y values are (524, 416).
  11. Debugging in action

Conclusion

There is too much to say about the VS.NET debugger for me to do it here. You would do well to familiarize yourself with its many options so that you can take advantage of all the features. Happy debugging.