michael@0: # The `Debugger` Interface
michael@0: 
michael@0: Mozilla's JavaScript engine, SpiderMonkey, provides a debugging interface
michael@0: named `Debugger` which lets JavaScript code observe and manipulate the
michael@0: execution of other JavaScript code. Both Firefox's built-in developer tools
michael@0: and the Firebug add-on use `Debugger` to implement their JavaScript
michael@0: debuggers. However, `Debugger` is quite general, and can be used to
michael@0: implement other kinds of tools like tracers, coverage analysis,
michael@0: patch-and-continue, and so on.
michael@0: 
michael@0: `Debugger` has three essential qualities:
michael@0: 
michael@0: - It is a *source level* interface: it operates in terms of the JavaScript
michael@0:   language, not machine language. It operates on JavaScript objects, stack
michael@0:   frames, environments, and code, and presents a consistent interface
michael@0:   regardless of whether the debuggee is interpreted, compiled, or
michael@0:   optimized. If you have a strong command of the JavaScript language, you
michael@0:   should have all the background you need to use `Debugger` successfully,
michael@0:   even if you have never looked into the language's implementation.
michael@0: 
michael@0: - It is for use *by JavaScript code*. JavaScript is both the debuggee
michael@0:   language and the tool implementation language, so the qualities that make
michael@0:   JavaScript effective on the web can be brought to bear in crafting tools
michael@0:   for developers. As is expected of JavaScript APIs, `Debugger` is a
michael@0:   *sound* interface: using (or even misusing) `Debugger` should never cause
michael@0:   Gecko to crash. Errors throw proper JavaScript exceptions.
michael@0: 
michael@0: - It is an *intra-thread* debugging API. Both the debuggee and the code
michael@0:   using `Debugger` to observe it must run in the same thread. Cross-thread,
michael@0:   cross-process, and cross-device tools must use `Debugger` to observe the
michael@0:   debuggee from within the same thread, and then handle any needed
michael@0:   communication themselves. (Firefox's builtin tools have a
michael@0:   [protocol][protocol] defined for this purpose.)
michael@0: 
michael@0: In Gecko, the `Debugger` API is available to chrome code only. By design,
michael@0: it ought not to introduce security holes, so in principle it could be made
michael@0: available to content as well; but it is hard to justify the security risks
michael@0: of the additional attack surface.
michael@0: 
michael@0: 
michael@0: ## Debugger Instances and Shadow Objects
michael@0: 
michael@0: `Debugger` reflects every aspect of the debuggee's state as a JavaScript
michael@0: value—not just actual JavaScript values like objects and primitives,
michael@0: but also stack frames, environments, scripts, and compilation units, which
michael@0: are not normally accessible as objects in their own right.
michael@0: 
michael@0: Here is a JavaScript program in the process of running a timer callback function:
michael@0: 
michael@0: ![A running JavaScript program and its Debugger shadows][img-shadows]
michael@0: 
michael@0: This diagram shows the various types of shadow objects that make up the
michael@0: Debugger API (which all follow some [general conventions][conventions]):
michael@0: 
michael@0: - A [`Debugger.Object`][object] represents a debuggee object, offering a
michael@0:   reflection-oriented API that protects the debugger from accidentally
michael@0:   invoking getters, setters, proxy traps, and so on.
michael@0: 
michael@0: - A [`Debugger.Script`][script] represents a block of JavaScript
michael@0:   code—either a function body or a top-level script. Given a
michael@0:   `Debugger.Script`, one can set breakpoints, translate between source
michael@0:   positions and bytecode offsets (a deviation from the "source level"
michael@0:   design principle), and find other static characteristics of the code.
michael@0: 
michael@0: - A [`Debugger.Frame`][frame] represents a running stack frame. You can use
michael@0:   these to walk the stack and find each frame's script and environment. You
michael@0:   can also set `onStep` and `onPop` handlers on frames.
michael@0: 
michael@0: - A [`Debugger.Environment`][environment] represents an environment,
michael@0:   associating variable names with storage locations. Environments may
michael@0:   belong to a running stack frame, captured by a function closure, or
michael@0:   reflect some global object's properties as variables.
michael@0: 
michael@0: The [`Debugger`][debugger-object] instance itself is not really a shadow of
michael@0: anything in the debuggee; rather, it maintains the set of global objects
michael@0: which are to be considered debuggees. A `Debugger` observes only execution
michael@0: taking place in the scope of these global objects. You can set functions to
michael@0: be called when new stack frames are pushed; when new code is loaded; and so
michael@0: on.
michael@0: 
michael@0: Omitted from this picture are [`Debugger.Source`][source] instances, which
michael@0: represent JavaScript compilation units. A `Debugger.Source` can furnish a
michael@0: full copy of its source code, and explain how the code entered the system,
michael@0: whether via a call to `eval`, a `<script>` element, or otherwise. A
michael@0: `Debugger.Script` points to the `Debugger.Source` from which it is derived.
michael@0: 
michael@0: All these types follow some [general conventions][conventions], which you
michael@0: should look through before drilling down into any particular type's
michael@0: specification.
michael@0: 
michael@0: All shadow objects are unique per `Debugger` and per referent. For a given
michael@0: `Debugger`, there is exactly one `Debugger.Object` that refers to a
michael@0: particular debuggee object; exactly one `Debugger.Frame` for a particular
michael@0: stack frame; and so on. Thus, a tool can store metadata about a shadow's
michael@0: referent as a property on the shadow itself, and count on finding that
michael@0: metadata again if it comes across the same referent. And since shadows are
michael@0: per-`Debugger`, tools can do so without worrying about interfering with
michael@0: other tools that use their own `Debugger` instances.
michael@0: 
michael@0: 
michael@0: ## Example
michael@0: 
michael@0: You can try out `Debugger` yourself in Firefox's Scratchpad.
michael@0: 
michael@0: 1)  Visit the URL `about:config`, and set the `devtools.chrome.enabled`
michael@0:     preference to `true`:
michael@0: 
michael@0:     ![Setting the 'devtools.chrome.enabled' preference][img-chrome-pref]
michael@0: 
michael@0: 2)  Save the following HTML text to a file, and visit the file in your
michael@0:     browser:
michael@0: 
michael@0:         <div onclick="var x = 'snoo'; debugger;">Click me!</div>
michael@0: 
michael@0: 3)  Open a developer Scratchpad (Menu button > Developer > Scratchpad), and
michael@0:     select "Browser" from the "Environment" menu. (This menu will not be
michael@0:     present unless you have changed the preference as explained above.)
michael@0: 
michael@0:     ![Selecting the 'browser' context in the Scratchpad][img-scratchpad-browser]
michael@0: 
michael@0: 4)  Enter the following code in the Scratchpad:
michael@0: 
michael@0:         // This simply defines 'Debugger' in this Scratchpad;
michael@0:         // it doesn't actually start debugging anything.
michael@0:         Cu.import("resource://gre/modules/jsdebugger.jsm");
michael@0:         addDebuggerToGlobal(window);
michael@0: 
michael@0:         // Create a 'Debugger' instance.
michael@0:         var dbg = new Debugger;
michael@0: 
michael@0:         // Get the current tab's content window, and make it a debuggee.
michael@0:         var w = gBrowser.selectedBrowser.contentWindow.wrappedJSObject;
michael@0:         dbg.addDebuggee(w);
michael@0: 
michael@0:         // When the debuggee executes a 'debugger' statement, evaluate
michael@0:         // the expression 'x' in that stack frame, and show its value.
michael@0:         dbg.onDebuggerStatement = function (frame) {
michael@0:             alert('hit debugger statement; x = ' + frame.eval('x').return);
michael@0:         }
michael@0: 
michael@0: 5)  In the Scratchpad, ensure that no text is selected, and press the "Run"
michael@0:     button.
michael@0: 
michael@0: 6)  Now, click on the text that says "Click me!" in the web page. This runs
michael@0:     the `div` element's `onclick` handler. When control reaches the
michael@0:     `debugger;` statement, `Debugger` calls your callback function, passing
michael@0:     a `Debugger.Frame` instance. Your callback function evaluates the
michael@0:     expression `x` in the given stack frame, and displays the alert:
michael@0: 
michael@0:     ![The Debugger callback displaying an alert][img-example-alert]
michael@0: 
michael@0: 7)  Press "Run" in the Scratchpad again. Now, clicking on the "Click me!"
michael@0:     text causes *two* alerts to show&mdash;one for each `Debugger`
michael@0:     instance.
michael@0: 
michael@0:     Multiple `Debugger` instances can observe the same debuggee. Re-running
michael@0:     the code in the Scratchpad created a fresh `Debugger` instance, added
michael@0:     the same web page as its debuggee, and then registered a fresh
michael@0:     `debugger;` statement handler with the new instance. When you clicked
michael@0:     on the `div` element, both of them ran. This shows how any number of
michael@0:     `Debugger`-based tools can observe a single web page
michael@0:     simultaneously&mdash;although, since the order in which their handlers
michael@0:     run is not specified, such tools should probably only observe, and not
michael@0:     influence, the debuggee's behavior.
michael@0: 
michael@0: 8)  Close the web page and the Scratchpad.
michael@0: 
michael@0:     Since both the Scratchpad's global object and the debuggee window are
michael@0:     now gone, the `Debugger` instances will be garbage collected, since
michael@0:     they can no longer have any visible effect on Firefox's behavior. The
michael@0:     `Debugger` API tries to interact with garbage collection as
michael@0:     transparently as possible; for example, if both a `Debugger.Object`
michael@0:     instance and its referent are not reachable, they will both be
michael@0:     collected, even while the `Debugger` instance to which the shadow
michael@0:     belonged continues to exist.
michael@0: 
michael@0: 
michael@0: ## Gecko-specific features
michael@0: 
michael@0: While the `Debugger` core API deals only with concepts common to any
michael@0: JavaScript implementation, it also includes some Gecko-specific features:
michael@0: 
michael@0: - [Global tracking][global] supports debugging all the code running in a
michael@0:   Gecko instance at once&mdash;the 'chrome debugging' model.
michael@0: - [Object wrapper][wrapper] functions help manipulate object references
michael@0:   that cross privilege boundaries.