DevTools/Features/Debugger

Feature	Status	ETA	Owner
DevTools/Features/Debugger	planning (some prototype/initial impl work done)	2011-05-13	Kevin Dangoor

Summary

Initial take on an integrated JavaScript debugger for Firefox.

Team

Have some thoughts on what you want out of a debugger? Inspiration on how to do it? Join us on #devtools on irc.mozilla.org

• Jim Blandy (irc: jimb): Remote debugging protocol, jsd2.
• Dave Camp (irc: dcamp): Firefox integration/UI, Remote debugging protocol.
• Jason Orendorff (irc: jorendorff): jsd2.

Repositories

• http://hg.mozilla.org/users/jblandy_mozilla.com/jsdbg2/ (JSD2)
• http://hg.mozilla.org/users/dcamp_campd.org/remote-debug/ (Remote Debugging Protocol/Firefox UI)

Release Requirements

TBD

Next Steps

• scope out the project

Related Bugs & Dependencies

See the status page for the bug list and current status.

Designs

TBD

Planning

What follows is some plan-related sketching, please update appropriately.

Milestone 1

• Working remote protocol, exposing stack frames with JSD2.
• Relying on debugger statement, no breakpoints.
• Only "continue" after stopping in debugger.
• UI shell in firefox
• UI for stack traces (without arguments)

Description	Area	Bug	Owner	Best	Likely	Worst	Status
Debugging global/Root actor registration/Socket Listener	Remote Proto		dcamp	2d	3d	5d
Browser root actor/tab actors (not as thread-like actors)	Browser Proto		dcamp	2d	2d	4d
Protocol handler thread (socket transport)	Remote Proto		dcamp	1d	1d	3d
Debug Object creation and debuggerHook	JSD2		jorendorff				In jsdbg2 branch.
Debug Object loader	JSD2ish		jorendorff				Similar to ctypes loader?
Debug Object support for frame inspection	JSD2		jorendorff				type, this, older, live, callee, generator, arguments complete.
Debug Object support for the toplevel globals in tab actor - debuggerHook spawning a nested event loop.	Browser Proto		dcamp	2d	2d	4d
New execution model specification in the remote protocol	Remote Proto		jimb
debuggerHook and "continue" exposed over remote protocol as specified.	Remote Proto		dcamp	3d	3d	5d	Need to see what new spec looks like...
Client JS API (socket transport)	UI Shell		dcamp	1d	2d	3d
HTML UI shell per tab, in its own window	UI Shell		dcamp	2d	2d	5d
UI responding to pauses (from debugger keyword)	Execution Handling		dcamp	2d	2d	4d
HTML Stack frame viewer (no locals/environment yet, just	Execution Handling		dcamp	2d	3d	5d

Milestone 2

Breaking on exceptions.

Description	Area	Bug	Owner	Best	Likely	Worst	Status
Debug object throw hook	JSD2		jorendorff
Throw hook exposed over the protocol	Remote Protocol/Execution Control		dcamp	1d	1d	3d
UI support for enabling/disabling/handling throw hook	UI Shell/Execution Control		dcamp	1d	1d	2d

Source Viewer

• Enough to visualize current line/stack frames/etc.
• No source list yet, will only reflect sources handed to it in pause states.
• Can use normal view source/firebug method (loading from necko preferring the cache) for getting static script sources (in-document <script> etc).
• Needs the engine to provide sources for exotic script sources (eval/appendNode/etc)

More Milestones

In no particular order...

• Source Selector
• Environment/Arguments/Properties viewer
• Stepping
• Breakpoints
• Web Worker debugging (might not be needed for an initial release, but would be really nice)
• Chrome debugging (probably not be needed for an initial release)

Floating Tasks

Here are a few tasks that I haven't slotted into any specific milestone, and could be tackled separately alongside the other milestones. At least some of these would block a final release of a capable debugger.

Description	Area	Bug	Owner	Best	Likely	Worst	Status
E10S content process support	Remote Proto		dcamp?	1w	3w	2w
Improved script origin information	JSD2	bug 637572	jimb
Waive slow script dialog (jorendorff was seeing them after resuming)	JSD2

Other

• Debug.addCompartment() - will need for cross-origin iframe support.

Basic Protocol Server

Basic implementation of the Remote Debugging Protocol.

Much of this stuff will likely be dependent on xpcom components in the firefox implementation (nsIServerSocket, nsIThreadManager, etc). As much as possible, we want to be able to retarget the implementation for projects outside of firefox, so this should be taken in to account.

None of this is implemented yet.

Protocol Transports

• Simple TCP socket protocol - Needed for remote debugging.
• Shouldn't need sockets for in-process debugging, can probably just post events directly to/from the handler thread.
• Need to figure out transport between chrome/content for e10s (See inter-process dispatch, below).
  • Content processes will need their own root actor that can enumerate/dispatch to tabs hosted in their process.
  • Presumably needs to use different APIs to list active tabs than we use in the chrome process (needs investigation).
  • Ask content processes to start up debugging host (chrome process will have UI cues, will probably just forward those to content processes over messageManager).
• WebSockets (not needed for an initial implementation).
• How do we represent the actor tree across multiple connections
  • Each connection is going to get its own debugger global/compartment in each thread.

Protocol Handler Thread

• Handles incoming protocol requests on a thread, needed to interrupt running script on other threads.
• Will handle transport IO as needed (for socket/websocket/etc transports).
• Handle inter-thread dispatching
  • Dispatching incoming protocol messages to actors on the proper thread.
  • An actor's parent or child might be on a different thread (for example when a browser tab actor might have a WebWorker actor as a child). Releasing a parent actor needs to release children, including on the other threads.
• Handle inter-process dispatching
  • Similar issues to inter-thread dispatch, but communicating to content processes using the debugging protocol.

Actor registration API

• Including maintenance of the actor tree.

Debugging compartments

• The debugger must be in a separate compartment from the debuggee, some sort of sandbox/new global-and-compartment for hosting a given connection's debugging actors on a thread.

Schedule Items

• Releasing actor subtrees
• Local Transport
• Browser root actor
• Browser tab actors
• e10s content process root actor

Protocol Client API

• With appropriate client-side transport support.

Browser Protocol Integration

Firefox-specific integration of the remote protocol.

Content Tab Contexts

• Will need to maintain a list of compartments needing debugging for the document tree loaded in the tab.
• Manage lifetimes and notifications related to navigation.
• Tabs exposed as a thread-like actor (or maybe with an immediate child for the main thread running in that tab?)

Chrome Context

• For debugging firefox.

WebWorker/ChromeWorker

• Related to inter-thread dispatch above. Likely to require some platform work on webworkers to get them to load the debug protocol implementation on startup?

Schedule Items

• Registration of worker actors (including notifying workers that they should be in debug mode or whatever)
• (some other things in schedule items elsewhere... splitting up schedule items by feature like this isn't a great plan)

UI Shell

• For basic debugging, want a single debugger UI per tab
  • Docked
  • Separate Window

• Unconnected debugging shell for connecting to remote debugging targets
  • Always separate window.

• Shell for debugging chrome.

• Until we get some spidermonkey improvements, we're going to need a reload to debug correctly
  • XXX jimb/jorendorff: please review this claim.
  • Ability to recompile scripts with debug support.
  • Firebug currently needs to observe creation to infer information (see elsewhere about script information)
  • Debugger UI per tab, either docked or separate window

• Connection management.

Stack Traces

JSD2 support

• Debug_Object#Debug.Frame
• Mostly (?) implemented in jsdbg2 branch.

Remote Protocol Support

• Remote_Debugging_Protocol#Listing_Stack_Frames
• Not implemented.

UI

• Not implemented.

UI Notes: Other Debuggers

Firebug

• Stack frame shows function name/source/line num, args
• Expand frames to view function args
• Selecting stack frame moves source view
• Right-clicking stack frames allowed viewing properties of function objects in the DOM tab.
• Breadcrumb view of the stack in the source view.

Chrome

• Stack frame shows function name/source/line
• Scope variables/environment in a different pane (see Environments)
• Selecting stack frame moves source view

Lexical Environments

JSD2

• Debug_Object#Debug.Environment
• Not implemented.
• (Uncategorized thought: frame.eval() is going to fail if it refers to a value that was optimized out of a closure. Jimb points out that the engine could conceivably notify that the value should have been there but isn't)

Remote Protocol Support

• Remote_Debugging_Protocol#Lexical_Environments
• Not implemented.

UI

• Not implemented.

UI Notes: Other Debuggers

Firebug:

• XXX: I couldn't find where/if firebug exposes lexical scopes.

Chrome:

• Scope chain exposed as a list, property viewers for each scope.

Execution Control

JSD2

• Debug_Object#Resumption_Values
• Debug_Object#Debug.Script (specifically "singleStepMode")
• Not implemented?

Remote Protocol Support

• Remote_Debugging_Protocol#Interacting_with_Thread-Like_Actors
• jimb mentioned on irc being unhappy with the pause/resume protocol, may need another spec iteration.
• Not implemented.

Implementation Notes

(this is a mess, ignore for now).

Pause Reasons:

• stepped
• pre-call
• pre-return
• pre-eval?

Breaking on exception:

• pre-throw/caught/uncaught

UI

Not implemented.

UI Notes

Chrome

• Allows toggling of throw/caught/uncaught pause reasons during execution.
• Pause/Continue/Step Over/Step Into/Step Out (finish)

Firebug

• Has Rerun/Continue/Step Into/Step Over/Step Out (finish)
• Calls pause Break-on-next (makes a bit more sense when spinning the event loop, and it can't actually pause?).

Schedule Items

• Basic Debug.Object actor support.

Breakpoints

JSD2

• Debug_Object#The_Debug_Object
• setBreakpoint/clearBreakpoint/clearAllBreakpoints
• Not implemented.

Protocol Support

• Remote_Debugging_Protocol#Breakpoints
• Not implemented.
• Looks like the protocol implementation will need to refcount breakpoints on the debug object (which has one-breakpoint-per-line) to support multiple breakpoints on a given line (potentially with different conditions).
• The protocol will also aggregate breakpoints on multiple scripts (for example, if the same script is loaded twice, there might be two scripts covering the same source location) for a given breakpoint actor.
• Protocol should be extended with breakpoint conditions?

UI

Not implemented.

UI Notes

Let's make sure you can edit a breakpoint's condition in the breakpoint list.

Firebug:

• Firebug uses disabled breakpoints to prevent stopping at debugger keywords.
• Breakpoint list:
  • function name
  • source name/line number
  • text of the source at that line
  • Checkbox to enable/disable
  • X button to delete.
• Seems to only allow one breakpoint per source line (at least from the ui).

Chrome:

• Breakpoint list:
  • source name/line number
  • text of the source at that line
  • Checkbox to enable/disable
  • Context menu to delete.
• Can "edit" (change a breakpoint's condition) a breakpoint from the source gutter, can't do that from the breakpoint list
• Seems to only allow one breakpoint per source line (at least from the UI).

Source List

https://bugzilla.mozilla.org/show_bug.cgi?id=637572

• This bug is important for proper handling of eval/event handlers/etc. Important early on, script loaders are common practice.
• Need to resource fixing this bug asap.

Firebug does a lot a crazy stuff to get scripts right for all origins (inline, eval, document.write, dom-appended script tags, etc). We'd prefer to avoid this with 637572, and we might be weaker than firebug with the more exotic sources in the meantime. XXX: Need to figure out exactly how much weaker.

Script sources:

• Static/inline scripts
  • Pretty well-understood
• Eval
• Event handlers
• document.write script tags
  • Can mess with line numbers.
• DOM injection of script tags/innerHTML

JSD2 support

• Debug_Object#Debug.Script
• Debug_Object#Debugging_hooks - newScript, specifically.
• Not implemented.

Protocol Support

• Debug_Object#Debugging_hooks
• Not implemented.

UI Notes

Chrome:

• Eval's show up in the source list as "(program)"
• Static sources are listed by basename (no disambiguation).
• Maintains a back-forward list for the source viewer.

Firebug:

• Shows evals
  • Given a name based on parent url (foo.html/eval/seq/1)
• Event handlers
  • Don't seem to show up unless you actually cause execution to stop in them (afaict)?
  • Given a name based on its parent url (foo.html/event/seq/1)
• Static source listed by basename with path headers for disambiguation.
• Maintains back-forward list for the source viewer.

Source Viewer

JSD2 Support

• Would be nice to have originalSource support in spidermonkey/JSD2, but none is currently specced/planned.

Protocol Support

• In the meantime, we can do protocol-side with necko (like firebug does currently).
• For the in-process content case, might want shortcut using the protocol.
• This needs spec thought.

UI Notes

Chrome:

• Line numbers/breakpoints/current line in gutter.
• Syntax highlighting
• Left-click in gutter sets/unsets breakpoint
• Right-click in gutter brings up a context menu with:
  • Continue to here
  • Add/Remove Breakpoint
  • Add Conditional Breakpoint
  • Disable Breakpoint

Firebug:

• Line numbers/breakpoints/current line in gutter.
• Line numbers seem to be colored by executability.
• No syntax highlighting
• Left-click in gutter sets/unsets breakpoint.
• Right-click in gutter sets conditional breakpoint.

Event Handling

• While stopped at the debugger spinning an event loop, we want to prevent event handlers from being processed by content.
• Right now that's done by firebug using nsDOMWindowUtils.suppressEventHandling().
• Prevents any interaction with the page at all: no selecting, scrolling, etc.
• Not sure how it interacts with XHR? XHR should be queued somehow.
• Would be nice to be able to select/scroll/etc on a stopped page, without allowing content handlers to run.
• Summary events would need to be sent for scrolling/etc, similar to the focus events currently sent by UnsupressEventHandling().