B2G/DeveloperPhone

Phone Development Environment

WINDOWS USERS: We do not currently support Windows as development platform. You can install a Linux VM using VMWare Player (see http://www.howtogeek.com/howto/11287/how-to-run-ubuntu-in-windows-7-with-vmware-player/).

The user interface on the phone is called "Gaia". It is hosted on gaiamobile.org, and offline cached on the device using appcache. At the moment the easiest way to modify Gaia is to check out the Gaia repository, modify the HTML5/JS source, and upload the new content to the phone. We will discuss this approach first:

1. First we need to checkout the Gaia source:

$ git clone https://github.com/andreasgal/gaia
Cloning into gaia...
remote: Counting objects: 14812, done.
remote: Compressing objects: 100% (5014/5014), done.
remote: Total 14812 (delta 9876), reused 14224 (delta 9345)
Receiving objects: 100% (14812/14812), 119.18 MiB | 1.46 MiB/s, done.
Resolving deltas: 100% (9876/9876), done.
$ cd gaia

2. The version of Gaia installed on developer phones is tagged "m2.5". You probably want to switch to that tag.

$ git checkout m2.5
Note: checking out 'm2.5'.

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by performing another checkout.

If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -b with the checkout command again. Example:

  git checkout -b new_branch_name

HEAD is now at 8b547e6... Merge pull request #1075 from krellian/owa

3. Next we will need adb, the Android Debugger Bridge. The easiest way to install adb is to install the Android SDK from this url:

http://developer.android.com/sdk/index.html

Make sure to install the Platform Tools (not installed by default).

4. Make sure adb is in your path.

$ adb
Android Debug Bridge version 1.0.26

 -d                            - directs command to the only connected USB device
                                 returns an error if more than one USB device is present.
...

5. You should be able to connect to the B2G phone via adb now:

$ adb shell
* daemon not running. starting it now on port 5037 *
* daemon started successfully *
root@android:/ # ^D
$ 

Control-D exits the shell again.

6. Now lets flash a new version of Gaia onto the phone:

Note: The first time install-gaia is invoked the Makefile will download xulrunner, which is used to build the appcache. Make sure you are connected to the network.

$ make install-gaia
git rev-parse HEAD > apps/settings/gaia-commit.txt
 	bbc
 	browser
 	calculator
	calendar
	camera
	clock
	cnn
	crystalskull
	cubevid
	cuttherope
	dialer
	facebook
	gallery
	gmail
	homescreen
	maps
	market
	music
	nytimes
	penguinpop
	settings
	sms
	towerjelly
	video
	wikipedia
	zimbra
test -d xulrunner-sdk || (wget http://ftp.mozilla.org/pub/mozilla.org/xulrunner/releases/11.0/sdk/xulrunner-11.0.en-US.mac-x86_64.sdk.tar.bz2 && tar xjf  xulrunner*.tar.bz2 && rm xulrunner*.tar.bz2) 
--2012-04-02 01:55:32--  http://ftp.mozilla.org/pub/mozilla.org/xulrunner/releases/11.0/sdk/xulrunner-11.0.en-US.mac-x86_64.sdk.tar.bz2
Resolving ftp.mozilla.org (ftp.mozilla.org)... 63.245.209.137
Connecting to ftp.mozilla.org (ftp.mozilla.org)|63.245.209.137|:80... connected.
HTTP request sent, awaiting response... 200 OK
Length: 56155841 (54M) [application/x-bzip2]
Saving to: `xulrunner-11.0.en-US.mac-x86_64.sdk.tar.bz2'

...

push: profile/webapps/video/manifest.json -> /data/local/webapps/video/manifest.json
push: profile/webapps/wikipedia/manifest.json -> /data/local/webapps/wikipedia/manifest.json
push: profile/webapps/zimbra/manifest.json -> /data/local/webapps/zimbra/manifest.json
push: profile/webapps/webapps.json -> /data/local/webapps/webapps.json
27 files pushed. 0 files skipped.
304 KB/s (25655 bytes in 0.082s)
Rebooting b2g now
adb shell kill 87

The phone should reboot and within about a second the new version of Gaia should be on the screen.

Advanced Gaia Hacking

You can find a lot of tips and instructions for advanced Gaia hacking at https://wiki.mozilla.org/Gaia/Hacking. Amongst others we have desktop builds of b2g, and you can use them to develop your app. In the alternative, you can also use Firefox, but watch out for differences between desktop and mobile (e.g. touch events).

For the particularly adventurous, you can also redirect the domain for an installed app in the /etc/hosts file on the phone to a server you own. Copy the files of an app onto the server and start modifying the code. To reload the UI on the phone, simply kill the b2g process. The following command line takes care of that:

adb shell kill `adb shell toolbox ps | grep "b2g" | awk '{ print $2; }'`

Restoring Gecko

Gecko is the "rendering engine", or "application runtime", on the device. It's the same engine that powers Firefox. The Gecko build on your phone is configured to automatically update itself. It should mostly stay out of your way.

However, if something does go wrong, you can repair your Gecko installation by running the following commands in your shell

curl update.boot2gecko.org/m2.5/b2g-gecko-m2.5-recovery.zip > b2g-gecko-m2.5-recovery.zip
unzip b2g-gecko-m2.5-recovery.zip
cd b2g-gecko-m2.5-recovery
make install-gecko