Starting the debugger
Debugging web content
To debug Web content running directly in Firefox (whether it's locally stored on your computer or on a server), choose the Debugger option from the Web Developer menu.
Once you've configured Firefox and Firefox OS for debugging support, you can use the Remote Debugger to debug your code running on a Firefox OS device or on the Firefox OS Simulator.
adb can see it. Then you need to forward the appropriate TCP port to the device by opening a terminal window and issuing the following command:
adb forward tcp:6000 tcp:6000
Reminder: You will have to re-forward the port any time you restart your device.
You can now open the remote debugger by choosing the Remote Debugger option from the Web Developer menu. This will ask you to specify the IP address and port to which you want to connect for debugging; unless you've changed this setting on the device, you can leave it set to
localhost:6000. Click OK and after a few moments, your debugger will be up and running.
At this point, the debugger isn't doing anything for you yet, because you haven't set any breakpoints or anything. The device just keeps on humming along. The following sections cover actually using the debugger.
The debugger toolbar
The toolbar has a number of controls:
- Pause/Resume (F6)
- Pauses or resumes execution of the script you're debugging.
- Step Over (F7)
- Step Into (F8)
- Step Out (Shift-F8)
- Runs the script until the current function exits.
- Script Chooser (Ctrl-P or Cmd-P)
- This pop-up menu lets you select one of the running scripts in order to read its code, set breakpoints, and so forth.
- Script Filter
- The script filter (which doubles as a search box) lets you type a string to filter what scripts should appear in the Script Chooser. See Using the script filter below.
- Expand Panes
- Expands or contracts the window to show or hide the sidebar panels.
- Debugger Options
- Pops up a menu letting you configure the debugger. See Debugger options below.
Note: The Web content debugger has a Close button at the far left end of the toolbar; you can use this to close the debugger.
Using the script filter
When you click in the script filter in the toolbar, you can type a string to filter the script chooser menu to only show matching scripts. Also, as you see when you click in this box, there are special operators you can use to use the box as a search box, as well as for other capabilities. Each of these special operators has a keyboard shortcut that will automatically take you to the filter box and insert the operator into the box for you, so that you can just start typing.
- Search in all files - ! (Cmd-Opt-F)
- Searches for the text you enter across all running scripts. This adds a pane just below the toolbar showing all the matching files, each with a disclosure box that lets you see the matches found within it.
- Find in this file - # (Cmd-F)
- Searches for the text you enter in the file you're currently looking at.
- Jump to line - : (Cmd-J)
- Jumps to the line number you type into the box.
- Filter variables - * (Cmd-Opt-V)
- Filters the displayed variables to include only those that match the specified string.
The Debugger Options icon, when clicked, presents a pop-up menu of options that you can use to adjust the behavior of the debugger.
- Pause on exceptions
- Show panes on startup
- When this option is enabled, the debugger's two sidebar panes are visible when you first start the debugger; by default, they are not.
- Show hidden properties
- Show variables searchbox
- Enabling this option adds a "Filter variables" search box to the variable panel, so that you can filter the displayed list of variables.
Using the debugger
You can set a breakpoint by choosing the file in which you want to set a breakpoint (if you're not already looking at it) using the script chooser drop-down menu, then clicking in the line number column, to the left of the line number itself, on the line of code on which you'd like to set a breakpoint. You can also right click in the code itself, on the line at which you'd like to create a breakpoint, and use the resulting contextual menu to create either a breakpoint (Ctrl+B or Cmd-B) or conditional breakpoint (Ctrl+Shift+B or Cmd-Shift-B).
For example, let's use the Remote Debugger to set a breakpoint that fires whenever you pull down the notification bar. To do that, choose "app://system.gaiamobile.org/js/quick_settings.js" (this is the quick settings app that appears when you pull down the notification bar). Go to the
handleEvent() method and click to the left of the first line of code. This will add a blue breakpoint indicator next to that line, like this:
You can toggle the breakpoint off again, of course, by clicking that breakpoint indicator again. The bottom of the stack panel also shows a list of all currently-set breakpoints. See Managing breakpoints for details on things you can do with this list.
Now, pull down the notification bar on your device. The bar will pull down, and then the breakpoint will fire as the app receives its first event. If you don't have the panes displayed, they will open at this time (in order to show you the stack frame, variable display, and so forth). The debugger will, at this point, look something like this:
Meanwhile, your device will look something like this:
You can click back and forth through the stack frame in order to take a look at the calling history. Clicking on "ut_onTouchEnd" in the stack frame panel will show you the code in
app://system.gaiamobile.org/js/utility_tray.js that handled the event that occurred when you removed your finger from the screen after pulling down the notification tray, for instance.
You can use the resume, step over, step into, and step out buttons in the toolbar just as in any typical debugger, to step through the code. The next line of code to run has a green arrow to its left. You can, of course, set and remove breakpoints, examine variables, and so forth while doing so.
The gutter to the right of the source code has blue indicators in it that you can click to quickly scroll to the corresponding breakpoint.
Then you can enter a condition which must be true for the breakpoint to be triggered:
Now, when the corresponding line of code is reached, it will only pause execution of the expression
evt.type == 'click' is true.
You can manage the breakpoints you've set using the breakpoint list along the lower-left side of your debugger window. Toggling on and off the checkbox to any breakpoint turns the breakpoint on and off. Clicking on any conditional breakpoint will pop up the conditional breakpoint editing panel, as seen in Conditional breakpoints.
You can get additional options by right-clicking on any breakpoint:
- Remove all breakpoints
- Removes all current breakpoints.
- Enable all breakpoints
- Enables all current breakpoints. This is a shortcut for toggling on the checkboxes next to all the breakpoints.
- Disable all breakpoints
- Disables (without removing) all breakpoints. This is a shortcut for toggling off the checkboxes next to all the breakpoints.
- Enable others
- Enables all breakpoints except the one you right-clicked.
- Disable others
- Disables all breakpoints except the one you right-clicked.
- Remove others
- Removes all breakpoints except the one you right-clicked.
- Configure conditional breakpoint
- Configures the conditional breakpoint on which you right-clicked. If the breakpoint isn't a conditional one, you can add a condition and turn it into a conditional breakpoint.
- Disable breakpoint
- Disables the breakpoint you right-clicked.
- Enable breakpoint
- Enables the breakpoint you right-clicked.
The variable panel
Most of the right-hand pane in the debugger is occupied by the variables available in the scope you're currently viewing. As seen here, it shows the variables for the local scope of the currently executing function (in this case,
qs_handleEvent()), the calling function (here it's
ut_show()), and the global scope (the
Window object, in this case).
Each object can be expanded using a disclosure triangle to show its members, thereby revealing its contents. You can change a variable's value by clicking on its current value and entering a new one; for example, if you click on the "true" next to
geolocationEnabled, you can type "false" to set the value to
false. Variables whose values you've edited are highlighted in yellow, like this:
Pointing your cursor at a variable provides a tooltip that provides additional information about the variable; for example, pointing at the
evt object says "
configurable enumerable writable". This tells you that the
evt object is not configurable, but is enumerable and writable. See
Object.defineProperty() for details on what these property descriptors mean.
If you've enabled the filter variables box, as shown in the screenshot, you can reduce clutter in this list to limit the list to showing only the things you really want to see. This search is even recursive; it will search through sub-objects. Typing "blue", for example, restricts the list to the
this.bluetooth object in the
qs_handleEvent() function's scope, and the
BluetoothTransfer objects in the global scope.
Then start running your code. The watch expression does nothing until you begin to step through your code, so nothing happens until you reach a breakpoint. At that point, a box showing your active watch expressions and their current values will appear.
For example, let's say we're stepping through some code and we want to quickly know what the value of a variable
a multiplied by two is, without having to be bothered with any tedious "thinking". We can enter the expression a*2 into the "Add a watch expression box" and hit enter, set an appropriate breakpoint, and run our code.
When our breakpoint is reached, let's say the value of
a is 1. The resulting display looks like this:
You can step through your code, watching the value of the expression as it changes; each time it does, the box will flash briefly yellow. You can remove a watch expression by clicking the "x" icon next to it, and, of course, you can have more than one watch expression at a time.
Stopping the debugger
When you're done debugging, if you like, you can turn off remote debugging on the device by opening the Settings app, then chosing Device Information. On that page, you'll see a More Information button. Tap that, then in the following page, scroll down to "Developer" and tap that. That presents a list of developer options. Turn off Remote Debugging there. You don't have to do this though, if you don't want to.
Note: No restart is needed just for toggling on and off remote debugging support on the device, as of Nightly builds from November 29, 2012 or later.]