jimblandy / debuggerdocs

Mozilla JavaScript Debugging Documentation

Mozilla JavaScript Debugging Documentation

This repository holds the specifications for:

• Mozilla's Debugger API, for implementing JavaScript debuggers and tools of that sort, and
• Mozilla's remote debugging protocol, for communicating with such debuggers over some sort of byte stream.

Officially, this documentation is on the Mozilla wiki—that's where the links take you—but we'd much rather use GitHub for revisions than MediaWiki's revision control, so we've checked it in here.

Branches

This repository's master branch tracks the wiki's contents. Revisions in progress, proposals for changes, and anything else that hasn't been placed on the wiki should go on a branch. Independent proposals should go on independent branches, I guess.

Ben's Birthday

Please join me in wishing Ben Collins-Sussman, a very fine fellow, a happy 40th birthday!

debuggerdocs's Issues

Getting the global of a frame

I haven't been able to find a clear way to get from a frame to its owning global. It may be possible to walk parent links until we get to a frame with type "call" or "global", and then use (frame.callee || frame.environment.object).global, but I'm not sure that's always correct, and in any case it seems rather fragile.

Can we add Debugger.Frame.global?

WeakMap introspection

For now, there is no way to introspect weakmaps, maps and sets.
For all, an accessor like .allKeys could do the job of enumerating all keys (which can be particularly useful for debugging WeakMaps).

Since WeakMap.prototype methods could be overridden in the debuggee, having reflection methods to map the prototype methods will also be necessary.

Getting a Debugger.Object without adding debuggees

Firebug wants to get Debugger.Objects for globals without having to go into debug mode, so that it can expose functions environments to content (wiki link), and use evalInGlobalWithBindings for command line evaluation, neither of which (seemingly) requires the global to be held as a debuggee. I presume that the Web Console also wants to avoid the perf impact of the latter.

There doesn't seem to be a technical reason for not having such an API, because as far as I can tell e.g.

s = /*unrelated window*/;
d = new Debugger;
d.enabled = false;
o = d.addDebuggee(s);
d.removeDebuggee(s);
g = o.makeDebuggeeValue(content).unwrap().global;
// g.evalInGlobalWithBindings, etc.

has the same effect (though it's a hack and also triggers debug mode in some unrelated compartment).

Could a Debugger.prototype.makeUnwrappedDebuggeeValue or Debugger.prototype.makeDebuggeeValueFromGlobal or something be added?

Or is it against the API design, with the aim instead being to fix debugger performance (e.g. bug 783428, bug 809563)?

Update docs relating to proxies to Direct Proxies api

There's probably no reason to support legacy Proxies, rather Direct Proxies should be supported. This calls for the removal of proxyCallTrap and proxyConstructTrap and the addition of proxyTarget. parameterNames should, instead of returning an empty array, return what parameterNames would return for the target. I think the whole class of DebuggeeWouldRun errors that arise from the debuggee being a proxy could probably be removed by simply forwarding them all to the target. While this would not paint a completely accurate picture of the proxy, it's better than simply giving up.

Docs should mention jsdebugger.jsm

As per the summary, it'd be nice if the docs said something about including jsdebugger.jsm, and its location. :-)

Likewise, the remote debugger docs should mention any components one needs there (have not yet looked into using those bits yet).

"setBreakpoint" packet shall belong to the source actor

https://wiki.mozilla.org/Remote_Debugging_Protocol#Breakpoints shows that setBreakpoint shall be send to a thread actor, however it looks like it shall be sent to a source. Also, the location parameter does not contain the url field, but might contain the condition.

Swank protocol port

Would it be possible to port this remote debugging protocol to a swank protocol and to provide a swank server for remote debugging? This would enable all slime-based front ends to make a remote debugging connection.

WebWorker introspection

IE10 is promising WebWorker debugging
It would be awesome to have that in JavaScript as well.

Document interraction with console actor

It is really useful to explain how "startListeners", "getCachedMessages", etc. messages and events of a tab console actor are working.

/cc @hbenl

Finer source code <=> offset information

Currently, the relationship between source code and bytecode instruction offsets is at the line granularity.
For instance the Debugger.Script.prototype.getLineOffsets method returns all bytecode instruction offsets for a given line. When setting a breakpoint on all of the offsets of this line (if there are several of them), it's impossible to know where in the source code this offset refers to. They just all refer to the same line.
Since some lines do a lot of things (like a for(i=0; i<=4 ; i++)), it could be convenient to know which instruction is being run within the same line (without having to tweak the source code just for that purpose).

Having the column information could be handy here.

An alternative could be to know where in the parse tree the breakpoint is.

Document Debugger.Script.prototype.isInCatchScope

This feature was introduced to help find out if an error will be caught somewhere in the stack.

Event loop introspection

Mark Miller's thesis contains a picture (page 107 of the document, Figure 14.2) of an E Vat which is somehow the equivalent of a JavaScript WebWorker. The context a webpage runs in is a vat.
A vat is made of a queue of "pending messages" which is what in the JavaScript world is called the event loop.
It would be great if it was possible to inspect, represent (and why not dynamically interact with) the event loop and the list of pending messages, very much like we currently can mess with the call stack.

Yay

Awesome

email fraud

Hackers