FirebugWiki - User contributions [en]

JSD2 Adoption

2013-05-16T06:47:15Z

Honza: /* Open Tasks */

== Resources ==
* [[Script Panel Refactoring]]
* [[Remoting Architecture]]
* [[Remote Selector]]

== Open Tasks ==
Rough list of missing things. The list should be converted into meaningful list of bug reports within Firebug issue tracker.

* <strike>Remove the old Script panel</strike>
** <strike>Remove also all related sidepanels</strike>
** <strike>Remove the firebug-service</strike>
** Remove BTI?
** <strike>Rename the new panel to “Script” (currently Debugger)</strike>
* Use ‘tabNavigated’ and ‘tabDetached’ to implement new TabWatcher
* Breakpoints
** <strike>Breakpoint removal (from the Script and Breakpoints panel)</strike>
** <strike>Conditional breakpoints</strike>
** <strike>Disable/Enable breakpoints</strike>
** <strike>Error breakpoints</strike>
** <strike>Monitor breakpoints</strike>
** <strike>XHR breakpoints (local scenario only)</strike>[https://bugzilla.mozilla.org/show_bug.cgi?id=832983 bug 832983], [https://bugzilla.mozilla.org/show_bug.cgi?id=821610 bug 821610]
** <strike>Mutation breakpoints</strike>
** DOM event breakpoints [https://bugzilla.mozilla.org/show_bug.cgi?id=800857 bug 800857], [https://bugzilla.mozilla.org/show_bug.cgi?id=832982 bug 832982]
** <strike>respect 'actualLocation' sent back from the server (corrected BP location)</strike>
** breakpoint initialization should be done when the target script (URL) is loaded.
** <strike>The breakpoint condition editor does not disappear when clicking outside of it.</strike>
** <strike>breakpoint info tip (condition)</strike>
** The bp-condition-editor doesn't scroll
* Use CodeMirror instead of Orion? See [https://bugzilla.mozilla.org/show_bug.cgi?id=816756 bug 816756]
* <strike>Pause on exception</strike>
* <strike>User expression in the Watch window</strike>
* <strike>Restore expanded state of the Watch window across stepping.</strike>
* Execute command line expression within the current frame
* New profiler API, see [https://bugzilla.mozilla.org/show_bug.cgi?id=797876 bug 797876]
* The autocompletion for “New watch expression” doesn’t allow to type just ‘a’ expression (always autocompleted to ‘atob’)
* Script panel context menu
** <strike>Copy Source</strike>
** <strike>Add Watch</strike>
** <strike>Toggle Breakpoint</strike>
** <strike>Toggle Disabled Breakpoint</strike>
** <strike>Continue, step over, step into, step out</strike>
** <strike>Edit Breakpoint Condition</strike>
** Run Until
** Rerun
* Meta: integration with other panels
** <strike>Break on… features</strike>
** Command line
** Console logging
** DOM panel
* <strike>Stack frames displayed in Script panel's toolbar</strike>
* Click on a function jumps to the definition
* <strike>Script panel info tip (var value)</strike>
* Adopt existing tests
* Scroll the script panel to show execution line
* Watch window: edit value and user variable name
* <strike>Break notifications (explaining the reason why break happened)</strike>
* <strike>The Script panel & two tabs with Firebug opened.</strike>
* <strike>Debugging two tabs at once (there is a warning).</strike>
* Source Maps: https://github.com/mozilla/source-map
* Script panel search
** Search multiple files
** Search for regular expression
** Goto line
* FirebugRep.supportsObject() could use third parameter for remote-object-types
** See also Simon's [https://github.com/firebug/firebug/commit/5c220f5ea1045e7921dd92d8c255e9e4b35b85d9#commitcomment-2536753 comment]
* The Watch panel
** Changing local variable or argument needs environment actor re-fetch from the server
* Script panel
** execution line disappears when switching to another tab and back
** When Firefox exists with the debugger active (context.stopped) the process hangs in the memory
** Mark executable lines

== Related Issues ==
Existing reports in Firebug issue list use label: jsd2 so, you can [http://code.google.com/p/fbug/issues/list?can=2&q=label%3Ajsd2 search] for them.

=== Bugzilla ===
* [https://bugzilla.mozilla.org/show_bug.cgi?id=800200 Bug 800200] - rm JSD
* [https://bugzilla.mozilla.org/show_bug.cgi?id=837723 Bug 837723] - Introduce a new method in IJSDebugger allowing to get DO referent.

JSD2 Adoption

2013-05-10T12:58:24Z

Honza: /* Open Tasks */

== Resources ==
* [[Script Panel Refactoring]]
* [[Remoting Architecture]]
* [[Remote Selector]]

== Open Tasks ==
Rough list of missing things. The list should be converted into meaningful list of bug reports within Firebug issue tracker.

* <strike>Remove the old Script panel</strike>
** <strike>Remove also all related sidepanels</strike>
** <strike>Remove the firebug-service</strike>
** Remove BTI?
** <strike>Rename the new panel to “Script” (currently Debugger)</strike>
* Use ‘tabNavigated’ and ‘tabDetached’ to implement new TabWatcher
* Breakpoints
** <strike>Breakpoint removal (from the Script and Breakpoints panel)</strike>
** <strike>Conditional breakpoints</strike>
** <strike>Disable/Enable breakpoints</strike>
** <strike>Error breakpoints</strike>
** <strike>Monitor breakpoints</strike>
** <strike>XHR breakpoints (local scenario only)</strike>[https://bugzilla.mozilla.org/show_bug.cgi?id=832983 bug 832983], [https://bugzilla.mozilla.org/show_bug.cgi?id=821610 bug 821610]
** <strike>Mutation breakpoints</strike>
** DOM event breakpoints [https://bugzilla.mozilla.org/show_bug.cgi?id=800857 bug 800857], [https://bugzilla.mozilla.org/show_bug.cgi?id=832982 bug 832982]
** <strike>respect 'actualLocation' sent back from the server (corrected BP location)</strike>
** breakpoint initialization should be done when the target script (URL) is loaded.
** <strike>The breakpoint condition editor does not disappear when clicking outside of it.</strike>
** <strike>breakpoint info tip (condition)</strike>
** The bp-condition-editor doesn't scroll
* Use CodeMirror instead of Orion? See [https://bugzilla.mozilla.org/show_bug.cgi?id=816756 bug 816756]
* <strike>Pause on exception</strike>
* <strike>User expression in the Watch window</strike>
* <strike>Restore expanded state of the Watch window across stepping.</strike>
* Execute command line expression within the current frame
* New profiler API, see [https://bugzilla.mozilla.org/show_bug.cgi?id=797876 bug 797876]
* The autocompletion for “New watch expression” doesn’t allow to type just ‘a’ expression (always autocompleted to ‘atob’)
* Script panel context menu
** <strike>Copy Source</strike>
** <strike>Add Watch</strike>
** <strike>Toggle Breakpoint</strike>
** <strike>Toggle Disabled Breakpoint</strike>
** <strike>Continue, step over, step into, step out</strike>
** <strike>Edit Breakpoint Condition</strike>
** Run Until
** Rerun
* Meta: integration with other panels
** <strike>Break on… features</strike>
** Command line
** Console logging
** DOM panel
* <strike>Stack frames displayed in Script panel's toolbar</strike>
* Click on a function jumps to the definition
* <strike>Script panel info tip (var value)</strike>
* Adopt existing tests
* Scroll the script panel to show execution line
* Watch window: edit value and user variable name
* <strike>Break notifications (explaining the reason why break happened)</strike>
* <strike>The Script panel & two tabs with Firebug opened.</strike>
* <strike>Debugging two tabs at once (there is a warning).</strike>
* Source Maps: https://github.com/mozilla/source-map
* Script panel search
** Search multiple files
** Search for regular expression
** Goto line
* FirebugRep.supportsObject() could use third parameter for remote-object-types
** See also Simon's [https://github.com/firebug/firebug/commit/5c220f5ea1045e7921dd92d8c255e9e4b35b85d9#commitcomment-2536753 comment]
* The Watch panel
** Changing local variable or argument needs environment actor re-fetch from the server
* Script panel
** execution line disappears when switching to another tab and back
** When Firefox exists with the debugger active (context.stopped) the process hangs in the memory

== Related Issues ==
Existing reports in Firebug issue list use label: jsd2 so, you can [http://code.google.com/p/fbug/issues/list?can=2&q=label%3Ajsd2 search] for them.

=== Bugzilla ===
* [https://bugzilla.mozilla.org/show_bug.cgi?id=800200 Bug 800200] - rm JSD
* [https://bugzilla.mozilla.org/show_bug.cgi?id=837723 Bug 837723] - Introduce a new method in IJSDebugger allowing to get DO referent.

Script Panel Refactoring

2013-05-09T12:58:51Z

Honza: /* Breakpoint Condition Editor */

This page summarizes refactoring the Firebug debugger to use JSD2 and adding support for remote JavaScript debugging. [http://code.google.com/p/fbug/issues/detail?id=5421 Issue 5421] tracks the actual changes done.

== Resources ==
Firebug Wiki:
* [[HTTP Monitor]]
* [[Firebug 1.7: Mozilla Backend|Firebug 1.7 BTI]]
* [[Net Panel Architecture Review]]
* [[Remoting Prototype#Prototype|Remoting Prototype]]
* [[Remoting Architecture|Remoting Architecture]]
* [[JSD2 Adoption|JSD2 Adoption]]

Mozilla Wiki:
* [https://wiki.mozilla.org/Debugger Debugger]
* [https://wiki.mozilla.org/Debugger_Client_API Debugger Client API]
* [https://developer.mozilla.org/en/SpiderMonkey/JS_Debugger_API_Guide JS Debugger API Guide]
* [https://developer.mozilla.org/en/SpiderMonkey/JS_Debugger_API_Reference JS Debugger API Reference]
* [https://wiki.mozilla.org/DevTools/Features/Debugger DevTools Debugger]
* [https://wiki.mozilla.org/Remote_Debugging_Protocol Remote Debugging Protocol]

== Goals ==
* Adopt JSD2 (get rid of all JSD1 APIs)
* Support remote debugging

== Related Issues ==
* [http://code.google.com/p/fbug/issues/detail?id=5421 Issue 5421]: Implement JSD2
* [http://code.google.com/p/fbug/issues/detail?id=5837 Issue 5837]: Implement remote debugging

== JSD2 API Requirements ==
The following list summarizes the high-level features that Firebug needs to support. It should be verified that all the features can re-implemented on top of JSD2 before starting the refactoring.

* List of scripts available on selected tab (including static, events and evaluated scripts) including iframes → <code>[https://developer.mozilla.org/en/SpiderMonkey/JS_Debugger_API_Reference/Debugger#findScripts%28%29 Debugger.findScripts()]</code>
* Stepping (into, over, out, resume, current line)
* Support for <code>debugger;</code> keyword → <code>[https://developer.mozilla.org/en/SpiderMonkey/JS_Debugger_API_Reference/Debugger#onDebuggerStatement%28%29 Debugger.onDebuggerStatement()]</code>
* Support for breakpoints (add, remove, enable, disabled, conditional, list of existing breakpoints) → <code>[https://developer.mozilla.org/en/SpiderMonkey/JS_Debugger_API_Reference/Debugger.Script#Methods Debugger.Script methods]</code>
* Recognize executable lines
* Dynamic eval in a frame (used e.g. by the [[Watch Side Panel]] when the debugger is halted) → <code>[https://developer.mozilla.org/en/SpiderMonkey/JS_Debugger_API_Reference/Debugger.Frame#eval%28%29 Debugger.Frame.eval()]</code> and <code>[https://developer.mozilla.org/en/SpiderMonkey/JS_Debugger_API_Reference/Debugger.Frame#evalWithBindings%28%29 Debugger.Frame.evalWithBindings()]</code>
* Get stack frames (including passed arguments) → <code>[https://developer.mozilla.org/en/SpiderMonkey/JS_Debugger_API_Reference/Debugger#getNewestFrame%28%29 Debugger.getNewestFrame()]</code> and <code>[https://developer.mozilla.org/en/SpiderMonkey/JS_Debugger_API_Reference/Debugger.Frame#Accessor_properties Debugger.Frame.older]</code>
* Scope chain variable exploring (with & closure scopes). It should be possible to see all values. → <code>[https://developer.mozilla.org/en/SpiderMonkey/JS_Debugger_API_Reference/Debugger.Frame#Accessor_properties Debugger.Frame.environment]</code>
* Break on next call
* Profiling (was part of JSD1)
* Tracking (break on) throw/catch/error → <code>[https://developer.mozilla.org/en/SpiderMonkey/JS_Debugger_API_Reference/Debugger#onThrow%28%29 Debugger.onThrow()]</code> and <code>[https://developer.mozilla.org/en/SpiderMonkey/JS_Debugger_API_Reference/Debugger#onError%28%29 Debugger.onError()]</code>
* Tracking (monitoring) function calls
* Freezing page UI if debugger is halted (including timeouts, intervals and worker threads)

=== Not Ready in JSD2 ===
* There is not source for evals.
* [https://developer.mozilla.org/en/SpiderMonkey/JS_Debugger_API_Reference/Debugger#onNewScript%28%29 new Function scripts?]
* [https://bugzilla.mozilla.org/show_bug.cgi?id=676586 Meta bug]: Implement a script Debugger
** As soon as this one is fixed
** Profiling is unrelated to JSD2. What is the plan here?
** Tracking (break on) throw/catch/error; also what is the plan?
* Conditional breakpoints ([https://bugzilla.mozilla.org/show_bug.cgi?id=740825 bug 740825])

== Current Debugger Architecture ==
This section describes the current debugger architecture.

[[File:Current-debugger-architecture.png]]

There are several layers/objects so, let's describe them step by step starting from the bottom.

* Backend: JSD1, FirebugService, Debugger
* Frontend: JavaScriptTool, ScriptPanel

=== JSD1 ===
This layer represents JSD1 platform API. These API allows to implement script debuggers and represent direct competition to JSD2 API. Of course this layer should entirely disappear and should be replaced by JSD2.

=== Firebug Service ===
Firebug service is implemented as [https://developer.mozilla.org/en-US/docs/JavaScript_code_modules/Using?redirectlocale=en-US&redirectslug=Using_JavaScript_code_modules js module] on top of JSD1 layer. The object is called ''FBS'' and it's purpose is to wrap JSD1 API so, they are not directly accessed anywhere else. This layer also maintain list of registered debuggers (usually <code>Firebug.Debugger</code> module) and fires various events to them (e.g. ''onToggleBreakpoint'', ''onToggleMonitor'', etc.) or execute theirs callback (e.g. ''onBreak'', ''onFunctionCall'', ''onError'', ''onThrow'', ''onScriptCreated'', etc.)

Main responsibilities:
* Activate/deactivate JSD in the browser. The activation is global for all current browser windows.
* Hook debugger events (interrupts, break on a breakpoint, etc.)
* Maintains list of registered debuggers (there is usually just one - Firebug debugger) and sends events to them.
* Manages nested event loop that is created for the debugger UI when page JS execution breaks.
* Sets/removes/enables/disables/saves/loads breakpoints
* Implements debugger stepping over/in/out/runUntil
* Monitors function calls
* Starts/stops profiling
* Tracks exceptions and errors (not working well)
* Tracks compiled scripts (not all of them)

=== Debugger ===
This object is derived from <code>Firebug.Module</code> and represents Firebug's debugger. It's also registered as a debugger into ''Firebug Service'' (FBS). This object should be the only one accessing FBS. It calls FBS API and receives various callbacks and events.

This object implements methods that can be used by the Script panel or other parts of Firebug (e.g. by those panels which implements BON).

Some examples of the API:
* ''evaluate'', ''evaluateInCallingFrame''
* ''breakNow'', ''getCurrentStackTrace''
* ''rerun''
* ''stepOver'', ''stepInto'', ''stepOut'', ''runUntil, ''resume''
* ''setBreakpoint'', ''clearBrakpoint'', etc.
* ''monitorFunction'', ''unmonitorFunction''
* ''monitorScript'', ''unmonitorScript''
* ''activateDebugger'', ''deactivateDebugger''

Implementation of these methods is based on FBS API.

There is also <code>Firebug.DebuggerListener</code> that defines the interface used by FBS
* ''onStop'', ''onResume'', ''onThrow'', ''onError'', ''onScriptCreated'' (there is more ''onScriptCreated'' events)

This object is ''observable'' and it activates the underlying JSD only if an observer exists. The observer is currently the Script panel even if it would make a bit more sense if it's actually the ''JavaScriptTool''.

=== JavaScriptTool ===
This object is part or BTI and represents a javascript debugger tool. This object is like a proxy sitting between <code>Firebug.Debugger</code> and the <code>ScriptPanel</code>. The current implementation is in-process only so, based on direct <code>Firebug.Debugger</code> API calls.

API of the tool is as follows:
* ''setBreakpoint'', ''clearBreakpoint'', ''enableBreakpoint'', ''disableBreakpoint'', ''isBreakpointDisabled'', ''getBreakpointCondition''
* ''rerun''
* ''resumeJavaScript'', ''stepOver'', ''stepInto'', ''stepOut'', ''runUntil''
* ''onConnect'', ''onDisconnect''
* ''onStartDebugging'', ''onStopDebugging''
* ''onCompilationUnit''

The BTI is used by [[Crossfire]]. Crossfire has the following structure:

Crossfire Panel
↓
Crossfire Module
↓
Crossfire Server
↓
Crossfire Socket Transport

When starting up it does the following.

# Register tools (e.g. console, inspector, ...)
# Start server
# Create socket transport
# Add BTI listener
# Set connection status

=== Script Panel ===
The [[Script Panel]] sits at the top of the whole stack of layers/objects. It represents the debugger UI (a view + a controller). The implementation of this object is quite extensive since it also includes the source code view and viewport (see <code>[https://github.com/firebug/firebug/blob/master/extension/content/firebug/js/sourceBox.js firebug/js/sourceBox.js]</code> module.

The ''Script'' panel should never access the <code>Firebug.Debugger</code> directly. It should always use the <code>JavaScriptTool</code>.

So, for example, if the user clicks on the Breakpoint Column, the action is handled by the ''Script'' panel, forwarded to the <code>JavaScriptTool</code>, which forwards it to the <code>Firebug.Debugger</code>, which forwards it to <code>FBS</code>. Finally, <code>FBS</code> is using JSD1 API to set the breakpoint.

There are side panels ([[Breakpoints Side Panel|Breakpoints]], [[Watch Side Panel|Watch]] and [[Stack Side Panel|Stack]]), which are synchronized automatically with the ''Script'' panel. They should all use <code>JavaScriptTool</code> to get appropriate data to display.

The synchronization happens through basic Firebug mechanisms like, <code>updateSelection</code> and <code>updateLocation</code>.

== New Debugger Architecture ==
=== Panels ===
The Script panel needs to be built on top of JSD2, remote protocol and Firebug remoting API. Remoting is already supported by [[HTTP Monitor]].

First of all, take a look a the following diagram.

[[Image:New-script-panel-architecture.png]]

* '''DebuggerClient''' This object comes from Firefox platform and is responsible for connection to the server back-end. The object maintains the underlying transport layer, it's responsible for tab attach/detach, it implements basic packets send and receive logic. The implementation is currently within ''resource://gre/modules/devtools/dbg-client.jsm'' module.

* '''DebuggerClientModule''' This module (singleton, one per Firebug instance) represents a wrapper around ''DebuggerClient''. It implements connection setup and initialization (e.g. port number). This object represents the ''connection'' in Firebug and should be shared by all ''remotable'' tools (e.g. the Script panel, Net panel, Profiler, etc.). Name of this module isn't probably descriptive enough, it could be changed. This object (or related object) could also replace the ''TabWatcher''.

* '''DebuggerTool''' This object implements API related to debugging (typical methods: stepIn, stepOut, setBreakpoint, etc.). The Script panel should always consume debugger API through this object. ''DebuggerTool'' registers itself as a ''DebuggerClientModule'' and thus gets all necessary events from the back-end (e.g. onConnect, onThreadAttached, etc.)

* '''ScriptPanel''' Represents debugger UI and listens mostly to ''onStartDebugging'' and ''onStopDebugging'' events. Those are used to properly updated the panel's UI.

* '''ScriptView''' This object is currently based on Orion (but could be replaced by CodeMirror, see [https://bugzilla.mozilla.org/show_bug.cgi?id=816756 bug 816756]). The main responsibility of this object is displaying the source code (using color syntax highlight).

* '''CallstackPanel''' This panel displays list of frames when the debugger is halted. The frame list is synchronized with ThreadClient's stack frame cache using ''framesadded'' and ''framescleared'' events.

* '''ThreadClient''' This object comes from Firefox platform and is responsible for tab-thread related logic.

* '''BreakpointStore''' Responsible for breakpoint persistence across Firefox restarts (in breakpoint.json file).

=== Grips ===
A grip represents handle to server side object (see [https://wiki.mozilla.org/Remote_Debugging_Protocol#Grips RDP] for more details).

Firebug framework introduces several objects that deals with these handles, see the next diagram.

[[File:Grips-architecture.jpg]]

* '''GripFactory''' This is the place where grips instances are created. Every grip object is associated with a '''class''' (see RDP) and uses '''Firebug.registerGrip''' to register itself. This factory uses a list of registered types and instantiates the right one according to the server side grip class attribute.

* '''GripCache''' The cache is the place where panels and other parts of Firebug should ask for grip-objects. If the requested object is not in the cache a request is sent to the backend and a promise synchronously returned and asynchronously resolved. If the object is already in the cache a promise is returned and synchronously resolved. '''GripCache''' is the only place, which uses '''GripFactory'''. See more about [https://getfirebug.com/wiki/index.php/Remoting_Architecture#Asynchronous_Data_Access asynchronous data access].

* '''ObjectGrip''' Represents a wrapper for '''RDP Grip'''

* '''Property''' Represents a wrapper for '''RDP Property'''

* '''FunctionGrip''' Represents a wrapper for a function object.

* '''ScopeGrip''' Represents a wrapper for a scope object. This object is used by the '''Watch''' panel to show chain of current scopes.

=== Breakpoints ===
This section describes architecture design for debugger breakpoints.

[[File:Breakpoints-architecture.png]]

* '''BreakpointStore''' The main component implementing public API for breakpoint creation and removal. This object is also responsible for client side persistence and initialization. There is one instance of this object per browser window (i.e. per Firebug). So, if a breakpoint is created in one context it automatically appears in all contexts that are using the same URL.
* '''FunctionMonitor''', '''ScriptPanel''', '''BreakpointPanel''', '''ConsolePanel''' These represent example objects that are dealing with breakpoints. There is and can be even more such objects in the future. All these objects use API implemented by '''BreakpointStore''' object. These objects also register themselves as ''DebuggerTool'' listeners to be notified about breakpoint related changes.
* '''DebuggerTool''' is responsible for breakpoint creation/removal on the server side. '''DebuggerTool''' registers itself as '''BreakpointStore''' listener to be notified about breakpoint creation/removal and sync the server side (i.e. create or remove breakpoints on the server side). There is one instance of this object per context.

See an example of a breakpoint creation (using the Script panel UI):

[[File:Breakpoint-add-sequence.png]]

* The user clicks on '''ScriptView''' breakpoint column. It's currently based on Orion, but it could be also CodeMirror in the future.
* '''ScriptView''' notifies '''ScriptPanel''' about the action.
* '''ScriptPanel''' is using '''BreakpointStore''' API to create a breakpoint. It calls ''addBreakpoint''. Breakpoint creation is asynchronous since the server side needs to be notified through TCP/IP. UI objects (e.g. panels) should wait for ''onBreakpointAdded'' event to update themselves.
* '''BreakpointStore''' sends ''onAddBreakpoint'' event to all registered listeners. These listeners are mostly all '''DebuggerTool''' instances (one per context) and also all UI object that want to display a temporary waiting-icon at the place where the breakpoint will (asynchronously) appear.
* '''DebuggerTool''' uses its associated '''ThreadClient''' to create a breakpoint on the server side. Each '''DebuggerTool''' instance will do it for its context. This way all contexts will be updated.
* '''ThreadClient''' sends packet to the server side and waits for asynchronous response.
* '''DebuggerTool''' has a direct (function) callback that is executed as soon as the response comes back from the server. Breakpoint's location is auto-corrected at this point if needed.
* '''DebuggerTool''' notifies all registered listeners (usually panels coming from the same context) about added breakpoint. It sends "onBreakpointAdded" event to the ''ScriptPanel'' in this scenario.
* '''ScriptPanel''' calls ''updateBreakpoint'' so, the '''ScriptView''' can update itself. Remove the waiting-icon and display the new breakpoint at the right location. It might also scroll to make sure that auto-corrected location is visible to the user.

==== Breakpoint Condition Editor ====
Let's yet see a sequence of actions describing what happens if '''BreakpointConditionEditor''' is opened at line with no breakpoint. In such case a breakpoint needs to be automatically created and used if the user actually creates a condition.

[[File:Breakpoint-condition-editor.png]]

* '''onGutterClick''' The user right clicks on the breakpoint column
* '''startBreakpointConditionEditor''' An event is sent to the '''ScriptPanel'''. Note that the '''ScriptView''' communicates with the '''ScriptPanel''' only through events.
* A helper '''initializeBreakpointConditionEditor''' is executed. This method creates a temporary BP structure with condition set to an empty string.
* '''initializeBreakpoint''' method is called to display breakpoint loading icon. The temporary BP is passed into it.
* The '''ScriptView''' sends '''addBreakpoint''' event back to the '''SccriptPanel'''. This event is fake and mimicking user click on the breakpoint column.
* The '''ScriptPanel''' uses '''BreakpointStore''' to add a breakpoint. Just like it always does if the user clicks on the breakpoint column to create (or remove) a breakpoint. But it passes the condition to it so, the breakpoint is not stored immediately (kind of a hack).
* '''BreakpointStore''' sends an event to all listeners, '''DebuggerTool''' instances - '''onAddBreakpoint'''.
* '''DebuggerTool''' sets the breakpoint on the server side. We need to do this before displaying the '''BreakpointConditionEditor''' since we need to know the correct line. Note that the user could have clicked on non-executable line.
* '''onBreakpointAdded''' event is sent from '''DebuggerTool''' to '''ScriptPanel''' and the condition editor can be finally displayed to the user by calling '''openBreakpointConditionEditor'''

''The entire feature is currently wired into the current breakpoint architecture. It should be rather implemented as an independent module''

Script Panel Refactoring

2013-05-09T12:57:07Z

Honza: /* Breakpoints */

File:Breakpoint-condition-editor.png

2013-05-09T12:45:15Z

Honza:

JSD2 Adoption

2013-04-18T11:44:39Z

Honza: /* Open Tasks */

== Resources ==
* [[Script Panel Refactoring]]
* [[Remoting Architecture]]
* [[Remote Selector]]

== Open Tasks ==
Rough list of missing things. The list should be converted into meaningful list of bug reports within Firebug issue tracker.

* <strike>Remove the old Script panel</strike>
** <strike>Remove also all related sidepanels</strike>
** <strike>Remove the firebug-service</strike>
** Remove BTI?
** <strike>Rename the new panel to “Script” (currently Debugger)</strike>
* Use ‘tabNavigated’ and ‘tabDetached’ to implement new TabWatcher
* Breakpoints
** <strike>Breakpoint removal (from the Script and Breakpoints panel)</strike>
** <strike>Conditional breakpoints</strike>
** <strike>Disable/Enable breakpoints</strike>
** <strike>Error breakpoints</strike>
** <strike>Monitor breakpoints</strike>
** <strike>XHR breakpoints (local scenario only)</strike>[https://bugzilla.mozilla.org/show_bug.cgi?id=832983 bug 832983], [https://bugzilla.mozilla.org/show_bug.cgi?id=821610 bug 821610]
** <strike>Mutation breakpoints</strike>
** DOM event breakpoints [https://bugzilla.mozilla.org/show_bug.cgi?id=800857 bug 800857], [https://bugzilla.mozilla.org/show_bug.cgi?id=832982 bug 832982]
** <strike>respect 'actualLocation' sent back from the server (corrected BP location)</strike>
** breakpoint initialization should be done when the target script (URL) is loaded.
** <strike>The breakpoint condition editor does not disappear when clicking outside of it.</strike>
** <strike>breakpoint info tip (condition)</strike>
** The bp-condition-editor doesn't scroll
* Use CodeMirror instead of Orion? See [https://bugzilla.mozilla.org/show_bug.cgi?id=816756 bug 816756]
* <strike>Pause on exception</strike>
* <strike>User expression in the Watch window</strike>
* <strike>Restore expanded state of the Watch window across stepping.</strike>
* Execute command line expression within the current frame
* New profiler API, see [https://bugzilla.mozilla.org/show_bug.cgi?id=797876 bug 797876]
* The autocompletion for “New watch expression” doesn’t allow to type just ‘a’ expression (always autocompleted to ‘atob’)
* Script panel context menu
** <strike>Copy Source</strike>
** <strike>Add Watch</strike>
** <strike>Toggle Breakpoint</strike>
** <strike>Toggle Disabled Breakpoint</strike>
** <strike>Continue, step over, step into, step out</strike>
** <strike>Edit Breakpoint Condition</strike>
** Run Until
** Rerun
* Meta: integration with other panels
** <strike>Break on… features</strike>
** Command line
** Console logging
** DOM panel
* <strike>Stack frames displayed in Script panel's toolbar</strike>
* Click on a function jumps to the definition
* Script panel info tip (var value)
* Adopt existing tests
* Scroll the script panel to show execution line
* Watch window: edit value and user variable name
* Break notifications (explaining the reason why break happened)
* The Script panel & two tabs with Firebug opened.
* <strike>Debugging two tabs at once (there is a warning).</strike>
* Source Maps: https://github.com/mozilla/source-map
* Script panel search
** Search multiple files
** Search for regular expression
** Goto line
* FirebugRep.supportsObject() could use third parameter for remote-object-types
** See also Simon's [https://github.com/firebug/firebug/commit/5c220f5ea1045e7921dd92d8c255e9e4b35b85d9#commitcomment-2536753 comment]
* The Watch panel
** Changing local variable or argument needs environment actor re-fetch from the server
* Script panel
** execution line disappears when switching to another tab and back
** When Firefox exists with the debugger active (context.stopped) the process hangs in the memory

== Related Issues ==
Existing reports in Firebug issue list use label: jsd2 so, you can [http://code.google.com/p/fbug/issues/list?can=2&q=label%3Ajsd2 search] for them.

=== Bugzilla ===
* [https://bugzilla.mozilla.org/show_bug.cgi?id=800200 Bug 800200] - rm JSD
* [https://bugzilla.mozilla.org/show_bug.cgi?id=837723 Bug 837723] - Introduce a new method in IJSDebugger allowing to get DO referent.

JSD2 Adoption

2013-04-17T16:29:09Z

Honza: /* Open Tasks */

== Resources ==
* [[Script Panel Refactoring]]
* [[Remoting Architecture]]
* [[Remote Selector]]

== Open Tasks ==
Rough list of missing things. The list should be converted into meaningful list of bug reports within Firebug issue tracker.

* <strike>Remove the old Script panel</strike>
** <strike>Remove also all related sidepanels</strike>
** <strike>Remove the firebug-service</strike>
** Remove BTI?
** <strike>Rename the new panel to “Script” (currently Debugger)</strike>
* Use ‘tabNavigated’ and ‘tabDetached’ to implement new TabWatcher
* Breakpoints
** <strike>Breakpoint removal (from the Script and Breakpoints panel)</strike>
** <strike>Conditional breakpoints</strike>
** <strike>Disable/Enable breakpoints</strike>
** <strike>Error breakpoints</strike>
** <strike>Monitor breakpoints</strike>
** <strike>XHR breakpoints (local scenario only)</strike>[https://bugzilla.mozilla.org/show_bug.cgi?id=832983 bug 832983], [https://bugzilla.mozilla.org/show_bug.cgi?id=821610 bug 821610]
** <strike>Mutation breakpoints</strike>
** DOM event breakpoints [https://bugzilla.mozilla.org/show_bug.cgi?id=800857 bug 800857], [https://bugzilla.mozilla.org/show_bug.cgi?id=832982 bug 832982]
** <strike>respect 'actualLocation' sent back from the server (corrected BP location)</strike>
** breakpoint initialization should be done when the target script (URL) is loaded.
** <strike>The breakpoint condition editor does not disappear when clicking outside of it.</strike>
** <strike>breakpoint info tip (condition)</strike>
** The bp-condition-editor doesn't scroll
* Use CodeMirror instead of Orion? See [https://bugzilla.mozilla.org/show_bug.cgi?id=816756 bug 816756]
* <strike>Pause on exception</strike>
* <strike>User expression in the Watch window</strike>
* <strike>Restore expanded state of the Watch window across stepping.</strike>
* Execute command line expression within the current frame
* New profiler API, see [https://bugzilla.mozilla.org/show_bug.cgi?id=797876 bug 797876]
* The autocompletion for “New watch expression” doesn’t allow to type just ‘a’ expression (always autocompleted to ‘atob’)
* Script panel context menu
** <strike>Copy Source</strike>
** <strike>Add Watch</strike>
** <strike>Toggle Breakpoint</strike>
** <strike>Toggle Disabled Breakpoint</strike>
** <strike>Continue, step over, step into, step out</strike>
** <strike>Edit Breakpoint Condition</strike>
** Run Until
** Rerun
* Meta: integration with other panels
** Break on… features
** Command line
** Console logging
** DOM panel
* <strike>Stack frames displayed in Script panel's toolbar</strike>
* Click on a function jumps to the definition
* Script panel info tip (var value)
* Adopt existing tests
* Scroll the script panel to show execution line
* Watch window: edit value and user variable name
* Break notifications (explaining the reason why break happened)
* The Script panel & two tabs with Firebug opened.
* Debugging two tabs at once.
* Source Maps: https://github.com/mozilla/source-map
* Script panel search
** Search multiple files
** Search for regular expression
** Goto line
* FirebugRep.supportsObject() could use third parameter for remote-object-types
** See also Simon's [https://github.com/firebug/firebug/commit/5c220f5ea1045e7921dd92d8c255e9e4b35b85d9#commitcomment-2536753 comment]
* The Watch panel
** Changing local variable or argument needs environment actor re-fetch from the server
* Script panel
** execution line disappears when switching to another tab and back
** When Firefox exists with the debugger active (context.stopped) the process hangs in the memory

== Related Issues ==
Existing reports in Firebug issue list use label: jsd2 so, you can [http://code.google.com/p/fbug/issues/list?can=2&q=label%3Ajsd2 search] for them.

=== Bugzilla ===
* [https://bugzilla.mozilla.org/show_bug.cgi?id=800200 Bug 800200] - rm JSD
* [https://bugzilla.mozilla.org/show_bug.cgi?id=837723 Bug 837723] - Introduce a new method in IJSDebugger allowing to get DO referent.

JSD2 Adoption

2013-04-17T14:52:12Z

Honza: /* Open Tasks */

== Resources ==
* [[Script Panel Refactoring]]
* [[Remoting Architecture]]
* [[Remote Selector]]

== Open Tasks ==
Rough list of missing things. The list should be converted into meaningful list of bug reports within Firebug issue tracker.

* <strike>Remove the old Script panel</strike>
** <strike>Remove also all related sidepanels</strike>
** <strike>Remove the firebug-service</strike>
** Remove BTI?
** <strike>Rename the new panel to “Script” (currently Debugger)</strike>
* Use ‘tabNavigated’ and ‘tabDetached’ to implement new TabWatcher
* Breakpoints
** <strike>Breakpoint removal (from the Script and Breakpoints panel)</strike>
** <strike>Conditional breakpoints</strike>
** <strike>Disable/Enable breakpoints</strike>
** <strike>Error breakpoints</strike>
** <strike>Monitor breakpoints</strike>
** <strike>XHR breakpoints (local scenario only)</strike>[https://bugzilla.mozilla.org/show_bug.cgi?id=832983 bug 832983], [https://bugzilla.mozilla.org/show_bug.cgi?id=821610 bug 821610]
** <strike>Mutation breakpoints</strike>
** DOM event breakpoints [https://bugzilla.mozilla.org/show_bug.cgi?id=800857 bug 800857], [https://bugzilla.mozilla.org/show_bug.cgi?id=832982 bug 832982]
** <strike>respect 'actualLocation' sent back from the server (corrected BP location)</strike>
** breakpoint initialization should be done when the target script (URL) is loaded.
** <strike>The breakpoint condition editor does not disappear when clicking outside of it.</strike>
** <strike>breakpoint info tip (condition)</strike>
** The bp-condition-editor doesn't scroll
* Use CodeMirror instead of Orion? See [https://bugzilla.mozilla.org/show_bug.cgi?id=816756 bug 816756]
* <strike>Pause on exception</strike>
* <strike>User expression in the Watch window</strike>
* <strike>Restore expanded state of the Watch window across stepping.</strike>
* Execute command line expression within the current frame
* New profiler API, see [https://bugzilla.mozilla.org/show_bug.cgi?id=797876 bug 797876]
* The autocompletion for “New watch expression” doesn’t allow to type just ‘a’ expression (always autocompleted to ‘atob’)
* Script panel context menu
** <strike>Copy Source</strike>
** <strike>Add Watch</strike>
** <strike>Toggle Breakpoint</strike>
** <strike>Toggle Disabled Breakpoint</strike>
** <strike>Continue, step over, step into, step out</strike>
** <strike>Edit Breakpoint Condition</strike>
** Run Until
** Rerun
* Meta: integration with other panels
** Break on… features
** Command line
** Console logging
** DOM panel
* <strike>Stack frames displayed in Script panel's toolbar</strike>
* Click on a function jumps to the definition
* Script panel info tip (var value)
* Adopt existing tests
* Scroll the script panel to show execution line
* Watch window: edit value and user variable name
* Break notifications (explaining the reason why break happened)
* The Script panel & two tabs with Firebug opened.
* Debugging two tabs at once.
* Source Maps: https://github.com/mozilla/source-map
* Script panel search
** Search multiple files
** Search for regular expression
** Goto line
* FirebugRep.supportsObject() could use third parameter for remote-object-types
** See also Simon's [https://github.com/firebug/firebug/commit/5c220f5ea1045e7921dd92d8c255e9e4b35b85d9#commitcomment-2536753 comment]
* The Watch panel
** Changing local variable or argument needs environment actor re-fetch from the server
* Script panel
** execution line disappears when switching to another tab and back

== Related Issues ==
Existing reports in Firebug issue list use label: jsd2 so, you can [http://code.google.com/p/fbug/issues/list?can=2&q=label%3Ajsd2 search] for them.

=== Bugzilla ===
* [https://bugzilla.mozilla.org/show_bug.cgi?id=800200 Bug 800200] - rm JSD
* [https://bugzilla.mozilla.org/show_bug.cgi?id=837723 Bug 837723] - Introduce a new method in IJSDebugger allowing to get DO referent.

Script Panel Refactoring

2013-04-15T10:57:55Z

Honza: /* Breakpoints */

Script Panel Refactoring

2013-04-15T10:48:02Z

Honza: /* Breakpoints */

This page summarizes refactoring the Firebug debugger to use JSD2 and adding support for remote JavaScript debugging. [http://code.google.com/p/fbug/issues/detail?id=5421 Issue 5421] tracks the actual changes done.

== Resources ==
Firebug Wiki:
* [[HTTP Monitor]]
* [[Firebug 1.7: Mozilla Backend|Firebug 1.7 BTI]]
* [[Net Panel Architecture Review]]
* [[Remoting Prototype#Prototype|Remoting Prototype]]
* [[Remoting Architecture|Remoting Architecture]]
* [[JSD2 Adoption|JSD2 Adoption]]

Mozilla Wiki:
* [https://wiki.mozilla.org/Debugger Debugger]
* [https://wiki.mozilla.org/Debugger_Client_API Debugger Client API]
* [https://developer.mozilla.org/en/SpiderMonkey/JS_Debugger_API_Guide JS Debugger API Guide]
* [https://developer.mozilla.org/en/SpiderMonkey/JS_Debugger_API_Reference JS Debugger API Reference]
* [https://wiki.mozilla.org/DevTools/Features/Debugger DevTools Debugger]
* [https://wiki.mozilla.org/Remote_Debugging_Protocol Remote Debugging Protocol]

== Goals ==
* Adopt JSD2 (get rid of all JSD1 APIs)
* Support remote debugging

== Related Issues ==
* [http://code.google.com/p/fbug/issues/detail?id=5421 Issue 5421]: Implement JSD2
* [http://code.google.com/p/fbug/issues/detail?id=5837 Issue 5837]: Implement remote debugging

== JSD2 API Requirements ==
The following list summarizes the high-level features that Firebug needs to support. It should be verified that all the features can re-implemented on top of JSD2 before starting the refactoring.

* List of scripts available on selected tab (including static, events and evaluated scripts) including iframes → <code>[https://developer.mozilla.org/en/SpiderMonkey/JS_Debugger_API_Reference/Debugger#findScripts%28%29 Debugger.findScripts()]</code>
* Stepping (into, over, out, resume, current line)
* Support for <code>debugger;</code> keyword → <code>[https://developer.mozilla.org/en/SpiderMonkey/JS_Debugger_API_Reference/Debugger#onDebuggerStatement%28%29 Debugger.onDebuggerStatement()]</code>
* Support for breakpoints (add, remove, enable, disabled, conditional, list of existing breakpoints) → <code>[https://developer.mozilla.org/en/SpiderMonkey/JS_Debugger_API_Reference/Debugger.Script#Methods Debugger.Script methods]</code>
* Recognize executable lines
* Dynamic eval in a frame (used e.g. by the [[Watch Side Panel]] when the debugger is halted) → <code>[https://developer.mozilla.org/en/SpiderMonkey/JS_Debugger_API_Reference/Debugger.Frame#eval%28%29 Debugger.Frame.eval()]</code> and <code>[https://developer.mozilla.org/en/SpiderMonkey/JS_Debugger_API_Reference/Debugger.Frame#evalWithBindings%28%29 Debugger.Frame.evalWithBindings()]</code>
* Get stack frames (including passed arguments) → <code>[https://developer.mozilla.org/en/SpiderMonkey/JS_Debugger_API_Reference/Debugger#getNewestFrame%28%29 Debugger.getNewestFrame()]</code> and <code>[https://developer.mozilla.org/en/SpiderMonkey/JS_Debugger_API_Reference/Debugger.Frame#Accessor_properties Debugger.Frame.older]</code>
* Scope chain variable exploring (with & closure scopes). It should be possible to see all values. → <code>[https://developer.mozilla.org/en/SpiderMonkey/JS_Debugger_API_Reference/Debugger.Frame#Accessor_properties Debugger.Frame.environment]</code>
* Break on next call
* Profiling (was part of JSD1)
* Tracking (break on) throw/catch/error → <code>[https://developer.mozilla.org/en/SpiderMonkey/JS_Debugger_API_Reference/Debugger#onThrow%28%29 Debugger.onThrow()]</code> and <code>[https://developer.mozilla.org/en/SpiderMonkey/JS_Debugger_API_Reference/Debugger#onError%28%29 Debugger.onError()]</code>
* Tracking (monitoring) function calls
* Freezing page UI if debugger is halted (including timeouts, intervals and worker threads)

=== Not Ready in JSD2 ===
* There is not source for evals.
* [https://developer.mozilla.org/en/SpiderMonkey/JS_Debugger_API_Reference/Debugger#onNewScript%28%29 new Function scripts?]
* [https://bugzilla.mozilla.org/show_bug.cgi?id=676586 Meta bug]: Implement a script Debugger
** As soon as this one is fixed
** Profiling is unrelated to JSD2. What is the plan here?
** Tracking (break on) throw/catch/error; also what is the plan?
* Conditional breakpoints ([https://bugzilla.mozilla.org/show_bug.cgi?id=740825 bug 740825])

== Current Debugger Architecture ==
This section describes the current debugger architecture.

[[File:Current-debugger-architecture.png]]

There are several layers/objects so, let's describe them step by step starting from the bottom.

* Backend: JSD1, FirebugService, Debugger
* Frontend: JavaScriptTool, ScriptPanel

=== JSD1 ===
This layer represents JSD1 platform API. These API allows to implement script debuggers and represent direct competition to JSD2 API. Of course this layer should entirely disappear and should be replaced by JSD2.

=== Firebug Service ===
Firebug service is implemented as [https://developer.mozilla.org/en-US/docs/JavaScript_code_modules/Using?redirectlocale=en-US&redirectslug=Using_JavaScript_code_modules js module] on top of JSD1 layer. The object is called ''FBS'' and it's purpose is to wrap JSD1 API so, they are not directly accessed anywhere else. This layer also maintain list of registered debuggers (usually <code>Firebug.Debugger</code> module) and fires various events to them (e.g. ''onToggleBreakpoint'', ''onToggleMonitor'', etc.) or execute theirs callback (e.g. ''onBreak'', ''onFunctionCall'', ''onError'', ''onThrow'', ''onScriptCreated'', etc.)

Main responsibilities:
* Activate/deactivate JSD in the browser. The activation is global for all current browser windows.
* Hook debugger events (interrupts, break on a breakpoint, etc.)
* Maintains list of registered debuggers (there is usually just one - Firebug debugger) and sends events to them.
* Manages nested event loop that is created for the debugger UI when page JS execution breaks.
* Sets/removes/enables/disables/saves/loads breakpoints
* Implements debugger stepping over/in/out/runUntil
* Monitors function calls
* Starts/stops profiling
* Tracks exceptions and errors (not working well)
* Tracks compiled scripts (not all of them)

=== Debugger ===
This object is derived from <code>Firebug.Module</code> and represents Firebug's debugger. It's also registered as a debugger into ''Firebug Service'' (FBS). This object should be the only one accessing FBS. It calls FBS API and receives various callbacks and events.

This object implements methods that can be used by the Script panel or other parts of Firebug (e.g. by those panels which implements BON).

Some examples of the API:
* ''evaluate'', ''evaluateInCallingFrame''
* ''breakNow'', ''getCurrentStackTrace''
* ''rerun''
* ''stepOver'', ''stepInto'', ''stepOut'', ''runUntil, ''resume''
* ''setBreakpoint'', ''clearBrakpoint'', etc.
* ''monitorFunction'', ''unmonitorFunction''
* ''monitorScript'', ''unmonitorScript''
* ''activateDebugger'', ''deactivateDebugger''

Implementation of these methods is based on FBS API.

There is also <code>Firebug.DebuggerListener</code> that defines the interface used by FBS
* ''onStop'', ''onResume'', ''onThrow'', ''onError'', ''onScriptCreated'' (there is more ''onScriptCreated'' events)

This object is ''observable'' and it activates the underlying JSD only if an observer exists. The observer is currently the Script panel even if it would make a bit more sense if it's actually the ''JavaScriptTool''.

=== JavaScriptTool ===
This object is part or BTI and represents a javascript debugger tool. This object is like a proxy sitting between <code>Firebug.Debugger</code> and the <code>ScriptPanel</code>. The current implementation is in-process only so, based on direct <code>Firebug.Debugger</code> API calls.

API of the tool is as follows:
* ''setBreakpoint'', ''clearBreakpoint'', ''enableBreakpoint'', ''disableBreakpoint'', ''isBreakpointDisabled'', ''getBreakpointCondition''
* ''rerun''
* ''resumeJavaScript'', ''stepOver'', ''stepInto'', ''stepOut'', ''runUntil''
* ''onConnect'', ''onDisconnect''
* ''onStartDebugging'', ''onStopDebugging''
* ''onCompilationUnit''

The BTI is used by [[Crossfire]]. Crossfire has the following structure:

Crossfire Panel
↓
Crossfire Module
↓
Crossfire Server
↓
Crossfire Socket Transport

When starting up it does the following.

# Register tools (e.g. console, inspector, ...)
# Start server
# Create socket transport
# Add BTI listener
# Set connection status

=== Script Panel ===
The [[Script Panel]] sits at the top of the whole stack of layers/objects. It represents the debugger UI (a view + a controller). The implementation of this object is quite extensive since it also includes the source code view and viewport (see <code>[https://github.com/firebug/firebug/blob/master/extension/content/firebug/js/sourceBox.js firebug/js/sourceBox.js]</code> module.

The ''Script'' panel should never access the <code>Firebug.Debugger</code> directly. It should always use the <code>JavaScriptTool</code>.

So, for example, if the user clicks on the Breakpoint Column, the action is handled by the ''Script'' panel, forwarded to the <code>JavaScriptTool</code>, which forwards it to the <code>Firebug.Debugger</code>, which forwards it to <code>FBS</code>. Finally, <code>FBS</code> is using JSD1 API to set the breakpoint.

There are side panels ([[Breakpoints Side Panel|Breakpoints]], [[Watch Side Panel|Watch]] and [[Stack Side Panel|Stack]]), which are synchronized automatically with the ''Script'' panel. They should all use <code>JavaScriptTool</code> to get appropriate data to display.

The synchronization happens through basic Firebug mechanisms like, <code>updateSelection</code> and <code>updateLocation</code>.

== New Debugger Architecture ==
=== Panels ===
The Script panel needs to be built on top of JSD2, remote protocol and Firebug remoting API. Remoting is already supported by [[HTTP Monitor]].

First of all, take a look a the following diagram.

[[Image:New-script-panel-architecture.png]]

* '''DebuggerClient''' This object comes from Firefox platform and is responsible for connection to the server back-end. The object maintains the underlying transport layer, it's responsible for tab attach/detach, it implements basic packets send and receive logic. The implementation is currently within ''resource://gre/modules/devtools/dbg-client.jsm'' module.

* '''DebuggerClientModule''' This module (singleton, one per Firebug instance) represents a wrapper around ''DebuggerClient''. It implements connection setup and initialization (e.g. port number). This object represents the ''connection'' in Firebug and should be shared by all ''remotable'' tools (e.g. the Script panel, Net panel, Profiler, etc.). Name of this module isn't probably descriptive enough, it could be changed. This object (or related object) could also replace the ''TabWatcher''.

* '''DebuggerTool''' This object implements API related to debugging (typical methods: stepIn, stepOut, setBreakpoint, etc.). The Script panel should always consume debugger API through this object. ''DebuggerTool'' registers itself as a ''DebuggerClientModule'' and thus gets all necessary events from the back-end (e.g. onConnect, onThreadAttached, etc.)

* '''ScriptPanel''' Represents debugger UI and listens mostly to ''onStartDebugging'' and ''onStopDebugging'' events. Those are used to properly updated the panel's UI.

* '''ScriptView''' This object is currently based on Orion (but could be replaced by CodeMirror, see [https://bugzilla.mozilla.org/show_bug.cgi?id=816756 bug 816756]). The main responsibility of this object is displaying the source code (using color syntax highlight).

* '''CallstackPanel''' This panel displays list of frames when the debugger is halted. The frame list is synchronized with ThreadClient's stack frame cache using ''framesadded'' and ''framescleared'' events.

* '''ThreadClient''' This object comes from Firefox platform and is responsible for tab-thread related logic.

* '''BreakpointStore''' Responsible for breakpoint persistence across Firefox restarts (in breakpoint.json file).

=== Grips ===
A grip represents handle to server side object (see [https://wiki.mozilla.org/Remote_Debugging_Protocol#Grips RDP] for more details).

Firebug framework introduces several objects that deals with these handles, see the next diagram.

[[File:Grips-architecture.jpg]]

* '''GripFactory''' This is the place where grips instances are created. Every grip object is associated with a '''class''' (see RDP) and uses '''Firebug.registerGrip''' to register itself. This factory uses a list of registered types and instantiates the right one according to the server side grip class attribute.

* '''GripCache''' The cache is the place where panels and other parts of Firebug should ask for grip-objects. If the requested object is not in the cache a request is sent to the backend and a promise synchronously returned and asynchronously resolved. If the object is already in the cache a promise is returned and synchronously resolved. '''GripCache''' is the only place, which uses '''GripFactory'''. See more about [https://getfirebug.com/wiki/index.php/Remoting_Architecture#Asynchronous_Data_Access asynchronous data access].

* '''ObjectGrip''' Represents a wrapper for '''RDP Grip'''

* '''Property''' Represents a wrapper for '''RDP Property'''

* '''FunctionGrip''' Represents a wrapper for a function object.

* '''ScopeGrip''' Represents a wrapper for a scope object. This object is used by the '''Watch''' panel to show chain of current scopes.

=== Breakpoints ===
This section describes architecture design for debugger breakpoints.

[[File:Breakpoints-architecture.png]]

* '''BreakpointStore''' The main component implementing public API for breakpoint creation and removal. This object is also responsible for client side persistence and initialization. There is one instance of this object per browser window (i.e. per Firebug). So, if a breakpoint is created in one context it automatically appears in all contexts that are using the same URL.
* '''FunctionMonitor''', '''ScriptPanel''', '''BreakpointPanel''', '''ConsolePanel''' These represent example objects that are dealing with breakpoints. There is and can be even more such objects in the future. All these objects use API implemented by '''BreakpointStore''' object. These objects also register themselves as ''DebuggerTool'' listeners to be notified about breakpoint related changes.
* '''DebuggerTool''' is responsible for breakpoint creation/removal on the server side. '''DebuggerTool''' registers itself as '''BreakpointStore''' listener to be notified about breakpoint creation/removal and sync the server side (i.e. create or remove breakpoints on the server side). There is one instance of this object per context.

See an example of a breakpoint creation (using the Script panel UI):

[[File:Breakpoint-add-sequence.png]]

* The user clicks on '''ScriptView''' breakpoint column. It's currently based on Orion, but it could be also CodeMirror in the future.
* '''ScriptView''' notifies '''ScriptPanel''' about the action.
* '''ScriptPanel''' is using '''BreakpointStore''' API to create a breakpoint. It calls ''addBreakpoint''. Breakpoint creation is asynchronous so, the return value is not useful. The panel must wait for ''onBreakpointAdded'' event instead.
* '''BreakpointStore''' sends ''onAddBreakpoint'' event to all registered listeners (in all contexts). The listeners will be most likely all '''DebuggerTool''' instances (one per context) and also all UI object that want to display a temporary waiting-icon at the place where the breakpoint will (asynchronously) appear.
* '''DebuggerTool''' uses its associated '''ThreadClient''' to create a breakpoint on the server side. Each '''DebuggerTool''' instance will do it for its context. This way all contexts will be updated. We might want to filter according to URL.
* '''ThreadClient''' sends packet to the server side and waits for asynchronous response.
* '''DebuggerTool''' has a direct (function) callback that is executed as soon as the response comes back from the server. Breakpoint's location is auto-corrected if needed.
* '''DebuggerTool''' directly access '''BreakpointStore''' and calls ''createBreakpoint''. Since '''BreakpointStore''' is a singleton, every context might try to create the same breakpoint. So, the tool just bails out if the same breakpoint already exists.
* '''BreakpointStore''' sends ''onBreakpointAdded'' to all listeners. So, in our case, the '''ScriptPanel''' also receives it.
* '''ScriptPanel''' calls ''updateBreakpoint'' so, the '''ScriptView''' can update itself. Remove the waiting-icon and display the new breakpoint at the right location. It might also scroll to make sure that auto-corrected location is visible to the user.

File:Breakpoint-add-sequence.png

2013-04-15T10:42:43Z

Honza: uploaded a new version of "File:Breakpoint-add-sequence.png"

File:Breakpoints-architecture.png

2013-04-15T10:41:39Z

Honza: uploaded a new version of "File:Breakpoints-architecture.png"

2013-04-05T12:19:14Z

Honza: /* Breakpoints */

This page summarizes refactoring the Firebug debugger to use JSD2 and adding support for remote JavaScript debugging. [http://code.google.com/p/fbug/issues/detail?id=5421 Issue 5421] tracks the actual changes done.

== Resources ==
Firebug Wiki:
* [[HTTP Monitor]]
* [[Firebug 1.7: Mozilla Backend|Firebug 1.7 BTI]]
* [[Net Panel Architecture Review]]
* [[Remoting Prototype#Prototype|Remoting Prototype]]
* [[Remoting Architecture|Remoting Architecture]]
* [[JSD2 Adoption|JSD2 Adoption]]

Mozilla Wiki:
* [https://wiki.mozilla.org/Debugger Debugger]
* [https://wiki.mozilla.org/Debugger_Client_API Debugger Client API]
* [https://developer.mozilla.org/en/SpiderMonkey/JS_Debugger_API_Guide JS Debugger API Guide]
* [https://developer.mozilla.org/en/SpiderMonkey/JS_Debugger_API_Reference JS Debugger API Reference]
* [https://wiki.mozilla.org/DevTools/Features/Debugger DevTools Debugger]
* [https://wiki.mozilla.org/Remote_Debugging_Protocol Remote Debugging Protocol]

== Goals ==
* Adopt JSD2 (get rid of all JSD1 APIs)
* Support remote debugging

== Related Issues ==
* [http://code.google.com/p/fbug/issues/detail?id=5421 Issue 5421]: Implement JSD2
* [http://code.google.com/p/fbug/issues/detail?id=5837 Issue 5837]: Implement remote debugging

== JSD2 API Requirements ==
The following list summarizes the high-level features that Firebug needs to support. It should be verified that all the features can re-implemented on top of JSD2 before starting the refactoring.

* List of scripts available on selected tab (including static, events and evaluated scripts) including iframes → <code>[https://developer.mozilla.org/en/SpiderMonkey/JS_Debugger_API_Reference/Debugger#findScripts%28%29 Debugger.findScripts()]</code>
* Stepping (into, over, out, resume, current line)
* Support for <code>debugger;</code> keyword → <code>[https://developer.mozilla.org/en/SpiderMonkey/JS_Debugger_API_Reference/Debugger#onDebuggerStatement%28%29 Debugger.onDebuggerStatement()]</code>
* Support for breakpoints (add, remove, enable, disabled, conditional, list of existing breakpoints) → <code>[https://developer.mozilla.org/en/SpiderMonkey/JS_Debugger_API_Reference/Debugger.Script#Methods Debugger.Script methods]</code>
* Recognize executable lines
* Dynamic eval in a frame (used e.g. by the [[Watch Side Panel]] when the debugger is halted) → <code>[https://developer.mozilla.org/en/SpiderMonkey/JS_Debugger_API_Reference/Debugger.Frame#eval%28%29 Debugger.Frame.eval()]</code> and <code>[https://developer.mozilla.org/en/SpiderMonkey/JS_Debugger_API_Reference/Debugger.Frame#evalWithBindings%28%29 Debugger.Frame.evalWithBindings()]</code>
* Get stack frames (including passed arguments) → <code>[https://developer.mozilla.org/en/SpiderMonkey/JS_Debugger_API_Reference/Debugger#getNewestFrame%28%29 Debugger.getNewestFrame()]</code> and <code>[https://developer.mozilla.org/en/SpiderMonkey/JS_Debugger_API_Reference/Debugger.Frame#Accessor_properties Debugger.Frame.older]</code>
* Scope chain variable exploring (with & closure scopes). It should be possible to see all values. → <code>[https://developer.mozilla.org/en/SpiderMonkey/JS_Debugger_API_Reference/Debugger.Frame#Accessor_properties Debugger.Frame.environment]</code>
* Break on next call
* Profiling (was part of JSD1)
* Tracking (break on) throw/catch/error → <code>[https://developer.mozilla.org/en/SpiderMonkey/JS_Debugger_API_Reference/Debugger#onThrow%28%29 Debugger.onThrow()]</code> and <code>[https://developer.mozilla.org/en/SpiderMonkey/JS_Debugger_API_Reference/Debugger#onError%28%29 Debugger.onError()]</code>
* Tracking (monitoring) function calls
* Freezing page UI if debugger is halted (including timeouts, intervals and worker threads)

=== Not Ready in JSD2 ===
* There is not source for evals.
* [https://developer.mozilla.org/en/SpiderMonkey/JS_Debugger_API_Reference/Debugger#onNewScript%28%29 new Function scripts?]
* [https://bugzilla.mozilla.org/show_bug.cgi?id=676586 Meta bug]: Implement a script Debugger
** As soon as this one is fixed
** Profiling is unrelated to JSD2. What is the plan here?
** Tracking (break on) throw/catch/error; also what is the plan?
* Conditional breakpoints ([https://bugzilla.mozilla.org/show_bug.cgi?id=740825 bug 740825])

== Current Debugger Architecture ==
This section describes the current debugger architecture.

[[File:Current-debugger-architecture.png]]

There are several layers/objects so, let's describe them step by step starting from the bottom.

* Backend: JSD1, FirebugService, Debugger
* Frontend: JavaScriptTool, ScriptPanel

=== JSD1 ===
This layer represents JSD1 platform API. These API allows to implement script debuggers and represent direct competition to JSD2 API. Of course this layer should entirely disappear and should be replaced by JSD2.

=== Firebug Service ===
Firebug service is implemented as [https://developer.mozilla.org/en-US/docs/JavaScript_code_modules/Using?redirectlocale=en-US&redirectslug=Using_JavaScript_code_modules js module] on top of JSD1 layer. The object is called ''FBS'' and it's purpose is to wrap JSD1 API so, they are not directly accessed anywhere else. This layer also maintain list of registered debuggers (usually <code>Firebug.Debugger</code> module) and fires various events to them (e.g. ''onToggleBreakpoint'', ''onToggleMonitor'', etc.) or execute theirs callback (e.g. ''onBreak'', ''onFunctionCall'', ''onError'', ''onThrow'', ''onScriptCreated'', etc.)

Main responsibilities:
* Activate/deactivate JSD in the browser. The activation is global for all current browser windows.
* Hook debugger events (interrupts, break on a breakpoint, etc.)
* Maintains list of registered debuggers (there is usually just one - Firebug debugger) and sends events to them.
* Manages nested event loop that is created for the debugger UI when page JS execution breaks.
* Sets/removes/enables/disables/saves/loads breakpoints
* Implements debugger stepping over/in/out/runUntil
* Monitors function calls
* Starts/stops profiling
* Tracks exceptions and errors (not working well)
* Tracks compiled scripts (not all of them)

=== Debugger ===
This object is derived from <code>Firebug.Module</code> and represents Firebug's debugger. It's also registered as a debugger into ''Firebug Service'' (FBS). This object should be the only one accessing FBS. It calls FBS API and receives various callbacks and events.

This object implements methods that can be used by the Script panel or other parts of Firebug (e.g. by those panels which implements BON).

Some examples of the API:
* ''evaluate'', ''evaluateInCallingFrame''
* ''breakNow'', ''getCurrentStackTrace''
* ''rerun''
* ''stepOver'', ''stepInto'', ''stepOut'', ''runUntil, ''resume''
* ''setBreakpoint'', ''clearBrakpoint'', etc.
* ''monitorFunction'', ''unmonitorFunction''
* ''monitorScript'', ''unmonitorScript''
* ''activateDebugger'', ''deactivateDebugger''

Implementation of these methods is based on FBS API.

There is also <code>Firebug.DebuggerListener</code> that defines the interface used by FBS
* ''onStop'', ''onResume'', ''onThrow'', ''onError'', ''onScriptCreated'' (there is more ''onScriptCreated'' events)

This object is ''observable'' and it activates the underlying JSD only if an observer exists. The observer is currently the Script panel even if it would make a bit more sense if it's actually the ''JavaScriptTool''.

=== JavaScriptTool ===
This object is part or BTI and represents a javascript debugger tool. This object is like a proxy sitting between <code>Firebug.Debugger</code> and the <code>ScriptPanel</code>. The current implementation is in-process only so, based on direct <code>Firebug.Debugger</code> API calls.

API of the tool is as follows:
* ''setBreakpoint'', ''clearBreakpoint'', ''enableBreakpoint'', ''disableBreakpoint'', ''isBreakpointDisabled'', ''getBreakpointCondition''
* ''rerun''
* ''resumeJavaScript'', ''stepOver'', ''stepInto'', ''stepOut'', ''runUntil''
* ''onConnect'', ''onDisconnect''
* ''onStartDebugging'', ''onStopDebugging''
* ''onCompilationUnit''

The BTI is used by [[Crossfire]]. Crossfire has the following structure:

Crossfire Panel
↓
Crossfire Module
↓
Crossfire Server
↓
Crossfire Socket Transport

When starting up it does the following.

# Register tools (e.g. console, inspector, ...)
# Start server
# Create socket transport
# Add BTI listener
# Set connection status

=== Script Panel ===
The [[Script Panel]] sits at the top of the whole stack of layers/objects. It represents the debugger UI (a view + a controller). The implementation of this object is quite extensive since it also includes the source code view and viewport (see <code>[https://github.com/firebug/firebug/blob/master/extension/content/firebug/js/sourceBox.js firebug/js/sourceBox.js]</code> module.

The ''Script'' panel should never access the <code>Firebug.Debugger</code> directly. It should always use the <code>JavaScriptTool</code>.

So, for example, if the user clicks on the Breakpoint Column, the action is handled by the ''Script'' panel, forwarded to the <code>JavaScriptTool</code>, which forwards it to the <code>Firebug.Debugger</code>, which forwards it to <code>FBS</code>. Finally, <code>FBS</code> is using JSD1 API to set the breakpoint.

There are side panels ([[Breakpoints Side Panel|Breakpoints]], [[Watch Side Panel|Watch]] and [[Stack Side Panel|Stack]]), which are synchronized automatically with the ''Script'' panel. They should all use <code>JavaScriptTool</code> to get appropriate data to display.

The synchronization happens through basic Firebug mechanisms like, <code>updateSelection</code> and <code>updateLocation</code>.

== New Debugger Architecture ==
=== Panels ===
The Script panel needs to be built on top of JSD2, remote protocol and Firebug remoting API. Remoting is already supported by [[HTTP Monitor]].

First of all, take a look a the following diagram.

[[Image:New-script-panel-architecture.png]]

* '''DebuggerClient''' This object comes from Firefox platform and is responsible for connection to the server back-end. The object maintains the underlying transport layer, it's responsible for tab attach/detach, it implements basic packets send and receive logic. The implementation is currently within ''resource://gre/modules/devtools/dbg-client.jsm'' module.

* '''DebuggerClientModule''' This module (singleton, one per Firebug instance) represents a wrapper around ''DebuggerClient''. It implements connection setup and initialization (e.g. port number). This object represents the ''connection'' in Firebug and should be shared by all ''remotable'' tools (e.g. the Script panel, Net panel, Profiler, etc.). Name of this module isn't probably descriptive enough, it could be changed. This object (or related object) could also replace the ''TabWatcher''.

* '''DebuggerTool''' This object implements API related to debugging (typical methods: stepIn, stepOut, setBreakpoint, etc.). The Script panel should always consume debugger API through this object. ''DebuggerTool'' registers itself as a ''DebuggerClientModule'' and thus gets all necessary events from the back-end (e.g. onConnect, onThreadAttached, etc.)

* '''ScriptPanel''' Represents debugger UI and listens mostly to ''onStartDebugging'' and ''onStopDebugging'' events. Those are used to properly updated the panel's UI.

* '''ScriptView''' This object is currently based on Orion (but could be replaced by CodeMirror, see [https://bugzilla.mozilla.org/show_bug.cgi?id=816756 bug 816756]). The main responsibility of this object is displaying the source code (using color syntax highlight).

* '''CallstackPanel''' This panel displays list of frames when the debugger is halted. The frame list is synchronized with ThreadClient's stack frame cache using ''framesadded'' and ''framescleared'' events.

* '''ThreadClient''' This object comes from Firefox platform and is responsible for tab-thread related logic.

* '''BreakpointStore''' Responsible for breakpoint persistence across Firefox restarts (in breakpoint.json file).

=== Grips ===
A grip represents handle to server side object (see [https://wiki.mozilla.org/Remote_Debugging_Protocol#Grips RDP] for more details).

Firebug framework introduces several objects that deals with these handles, see the next diagram.

[[File:Grips-architecture.jpg]]

* '''GripFactory''' This is the place where grips instances are created. Every grip object is associated with a '''class''' (see RDP) and uses '''Firebug.registerGrip''' to register itself. This factory uses a list of registered types and instantiates the right one according to the server side grip class attribute.

* '''GripCache''' The cache is the place where panels and other parts of Firebug should ask for grip-objects. If the requested object is not in the cache a request is sent to the backend and a promise synchronously returned and asynchronously resolved. If the object is already in the cache a promise is returned and synchronously resolved. '''GripCache''' is the only place, which uses '''GripFactory'''. See more about [https://getfirebug.com/wiki/index.php/Remoting_Architecture#Asynchronous_Data_Access asynchronous data access].

* '''ObjectGrip''' Represents a wrapper for '''RDP Grip'''

* '''Property''' Represents a wrapper for '''RDP Property'''

* '''FunctionGrip''' Represents a wrapper for a function object.

* '''ScopeGrip''' Represents a wrapper for a scope object. This object is used by the '''Watch''' panel to show chain of current scopes.

=== Breakpoints ===

TODO

[[File:Breakpoints-architecture.png]]

[[Breakpoint-add-sequence.png]]

File:Breakpoint-add-sequence.png

2013-04-05T12:19:01Z

Honza:

2013-01-30T11:23:43Z

Honza: /* Open Tasks */

2013-01-16T12:44:23Z

Honza: /* Open Issues */

JSD2 Adoption

2013-01-16T06:55:14Z

Honza: /* Open Issues */