Debugger Architecture

The Script Debugger in Firefox is composed of a number of separate subsystems that work in concert to provide this user experience. This document will hopefully serve as a guide for everyone who would like to gain a better understanding on how it works, as well as the reasoning behind some of the design decisions.

Overview

There are two main parts to the Script Debugger: the front-end part and the Debugger server that interfaces with the script that is running on the page. These two parts communicate through the Remote Debugging Protocol in a traditional client-server architecture, exchanging messages specified as JSON objects. The protocol implementation resides in toolkit/devtools/debugger, while the debugger UI can be found in browser/devtools/debugger.

The protocol implementation

The debugger server consists of the files in toolkit/devtools/debugger/server. The main module is dbg-server.jsm. This module creates a sandbox in a separate compartment and loads the dbg-server.js code in it. dbg-server.js contains the core server logic that handles listening for and responding to connections, handling protocol packets and manipulating actor pools. For more information on actors see the Remote Debugging Protocol. The other two files in that directory contain definitions for particular families of actors. dbg-script-actors.js specifies essential actors for debugging a JavaScript program: thread (or JavaScript context) actors, object actors, (stack) frame actors, environment actors, breakpoint actors, etc. dbg-browser-actors.js contains actors pertinent to a web browser, like the root (or browser) actor and tab actors. These modules use the Debugger API for debugging the script in the page.

Outside of the server/ directory, we can find 3 separate things. The first is dbg-client.jsm, a module for hiding the remote debugging protocol behind an easy to use JavaScript API. The second is dbg-transport.js, which contains the low-level code that handles the protocol connection for both client and server. And the last thing is nsIJSInspector, a native helper component for entering and exiting nested event loops.

The Debugger UI

The client part of the client-server architecture (modulo the dbg-client.jsm library) resides in browser/devtools/debugger. There we can find the DebuggerUI.jsm module that serves as the main entry point from the browser to the Script Debugger, as well as the home for supplementary functions that interface with the rest of the browser (storing preferences, loading files, etc.). The main UI document, debugger.xul loads two more scripts, debugger.js and debugger-view.js: debugger.js contains the controller functions, while debugger-view.js contains the view functions in a traditional MVC separation. In other words, debugger-view.js handles all things visual and debugger.js mediates between user actions and protocol messages to control the debugged script.