Friday, October 5, 2012

Debugging Firefox OS

A few months ago, long before the Firefox debugger had shipped, I had tried to see what it would take to get it to debug B2G, or as we call it now, Firefox OS. The hack proved successful and with time it grew into an important debugging target for us. I demoed it at JSConf last April, but at that time a lot of the debugger frontend functionality had not been available in nightlies. As of yesterday, however, nightly builds of Firefox can debug nightly builds of Firefox OS, both in the device and desktop versions. Let me give you a quick rundown of the necessary steps.

First of all you need to go to about:config on your desktop Firefox and turn devtools.debugger.remote-enabled to true. After restarting Firefox you will have a new Remote Debugger menu item in your Web Developer menu.

You need to change the same setting in Firefox OS as well, and that requires finding the prefs.js file. For desktop builds, this will be in gaia-repository/profile/prefs.js. For devices, you should connect it to the desktop through a USB cable, use adb shell to connect to the device, and find the name of the default profile in /data/b2g/mozilla/. The prefs.js file wil be in that subdirectory, which in my case is /data/b2g/mozilla/ngsweij3.default/prefs.js. You can get that file off the device using:

adb pull /data/b2g/mozilla/ngsweij3.default/prefs.js prefs.js
 
That will store a copy of that file in your current working directory. You need to modify this file and then send it back to the device with:

adb push prefs.js /data/b2g/mozilla/ngsweij3.default/prefs.js

The necessary changes to that file are the following two lines:

user_pref("devtools.debugger.remote-enabled", true);
user_pref("marionette.defaultPrefs.enabled", false);

They enable the debugger server and at the same time disable the Marionette server, to avoid a conflict that we haven’t resolved yet.

That is all that is necessary for the desktop Firefox OS case, but you need to do one more thing for debugging Firefox OS on the device. If you are going to debug over a USB connection (which will also provide helpful console logs via adb logcat) you will need to forward a local port to the device using adb:

adb forward tcp:6000 tcp:6000

Port number 6000 is the default and if you need to change it for some reason, you can do so with the following pref:

user_pref("devtools.debugger.remote-port", 7000);

Debugging over WiFi is also possible, although disabled by default, so you will need to change the following pref to do so:

user_pref("devtools.debugger.force-local", false);

In that case, you don’t have to do the port forwarding step, but you may change the port number in the same way.

In order for the new settings to take effect in the device you have to restart it with ‘adb reboot’.

That’s all folks! Now you just start your nightly Firefox and select the Remote Debugger menu item. A dialog will pop up asking for the remote address and port number to connect to. The defaults will work for the desktop Firefox OS or the device debugging-over-USB cases (unless you changed the port number of course!). If you opted for debugging over WiFi, you will need to provide the IP address of the device. You can find it by tapping on the connection name in the settings.

After the connection is established, you will see a list of the sources loaded on the device, giving you the option to inspect the code, set breakpoints, step through the execution or even modify the values of variables. Here is a screencast that shows the debugger in action:



A better introductory guide to debugging Firefox OS will be available soon on MDN. This is just the first step in supporting Firefox OS development with Firefox developer tools. Just around the corner are web console support and profiling, with more to follow in the near future. If you have issues or suggestions for these tools, please get in touch! Post a comment, file a bug or pop in #devtools for a chat. Let's make the web the best platform to develop on!

9 comments:

Anonymous said...

One easy way to add custom prefs is to put them in a file name custom-prefs.js in your gaia directory. The build system then adds them to user.js for you.

Panagiotis Astithas said...

I didn't know that and it is indeed very convenient, thanks!

Donovan Preston said...

Awesome blog post, thanks! I'm really glad to know the source over the wire bug is fixed for the debugger. This will make debugging firefox os much easier.

Is there any chance for JavaScript profiling tools any time soon?

Panagiotis Astithas said...

Absolutely, the upcoming profiler tool is being tracked in:
https://bugzilla.mozilla.org/show_bug.cgi?id=795268

But there is already an add-on you can use as the frontend to the gecko profiler:
https://developer.mozilla.org/en-US/docs/Performance/Profiling_with_the_Built-in_Profiler

Donovan Preston said...

Great, thank you very much :-)

Anonymous said...

I have a problem about running remote debuger.

It seems that the connection is successful but debugger cant't load javascript code.
The remote debugger display 'loading' text when I select a javascript file.

I added prefs.js file the below lines:
user_pref("devtools.debugger.remote-enabled", true);
user_pref("marionette.defaultPrefs.enabled", false);
// the below lines are optional
user_pref("devtools.webconsole.remote-host", "localhost");
user_pref("devtools.webconsole.remote-port", 6000);

Panagiotis Astithas said...

Can you file a bug so we can debug this? Following this link will get you to the right product and component:

https://bugzilla.mozilla.org/enter_bug.cgi?product=Firefox&component=Developer%20Tools%3A%20Debugger

Anonymous said...

Tell me how to debug with firebug, or use a selector tool (point to show HTML) and then we've got something.

Panagiotis Astithas said...

There has been a lot of progress since this post was written. A new tool called App Manager will do what you are looking for in recent versions of Firefox and Firefox OS:

https://developer.mozilla.org/docs/Mozilla/Firefox_OS/Using_the_App_Manager

Creative Commons License Unless otherwise expressly stated, all original material in this weblog is licensed under a Creative Commons Attribution 3.0 License.