2013-04-22
Running Firefox OS on Nexus S
Update: 2013-05-07: Minor changes to deal with new and rebased patches.
Last year I posted about how to build and run B2G on the Nexus S. Much has changed since then and this post attempts to provide up to date instructions on building Firefox OS and installing the latest Gaia version.
I wrote 'attempts' because the support for the Nexus S bitrots frequently due to (I assume) most development effort going towards developer devices and devices that intend to be shipped. These instructions worked for me on my Nexus S and gives me a phone that can use Wifi, make calls, use 3G data, take photo's, record video and install applications.
Getting the source
The main source repository is on github, https://github.com/mozilla-b2g/b2g. The first step is to clone this repository. I clone this into a directory called nexus-s:
$ git clone git://github.com/mozilla-b2g/B2G nexus-s
$ cd nexus-s
Create a file in this directory called .userconfig containing the following:
export CC=gcc-4.6
export CXX=g++-4.6
export HIDPI=1
The first two entries are required if you are building on Ubuntu 12.10 to use gcc version 4.6, which you must install. B2G does not build using gcc version 4.7.
The last entry, HIDPI, results in applications using the correct resources for the screen size on the Nexus S. Without this many things will be scaled incorrectly.
Configuring
Once the source is obtained you need to pull down the sub-repositories required for the Nexus S. This step downloads multiple gigabytes of data and can take a long time:
nexus-s$ BRANCH=v1-train ./config.sh nexus-s
Note the use of the BRANCH environment variable. This configures our build to use the relatively stable v1-train branch. This branch gets regular updates but tends to be better tested than master which is often broken for not-quite-supported devices like the Nexus S.
Although we are using the v1-train we are going to use the master branch of Gaia so we get the latest and greatest user interface. We'll change to this later.
Gecko changes
The branch of Gecko that v1-train uses has some bugs on the Nexus S. To fix this we need to apply some patches. The first is bug 832653, video playback broken on Nexus S. The patches relevant to Gecko from this bug that need to be applied are:
The following set of commands downloads these patches and applies them in a branch of the Gecko tree that the config.sh step previously obtained:
nexus-s $ cd gecko
nexus-s/gecko $ git checkout -b nexus-s m/v1-train
nexus-s/gecko $ curl -k -L https://bug832653.bugzilla.mozilla.org/attachment.cgi?id=734988 >p1.patch
nexus-s/gecko $ patch -p1 <p1.patch
nexus-s/gecko $ git commit -a -m "Nexus S patches"
nexus-s/gecko $ cd ..
Gonk changes
Part of bug 832653 makes a change to the low level Gonk layer of B2G. This is in the libstagefright video decoding libraries. The change is to prevent output buffer starvation which results in video decoding stopping after a few frames. The required patch is:
To apply this patch:
nexus-s $ cd frameworks/base
nexus-s/frameworks/base $ git checkout -b nexus-s
nexus-s/frameworks/base $ curl -k -L https://bugzilla.mozilla.org/attachment.cgi?id=735002 >p1.patch
nexus-s/frameworks/base $ patch -p1 <p1.patch
nexus-s/frameworks/base $ git commit -a -m "Nexus S patches"
nexus-s/frameworks/base $ cd ../..
Gaia changes
There are Gaia changes required as part of bug 869289 as well. This change prevents the error where videos are not listed if the thumbnail cannot be generated:
We also want to be on the Gaia master branch to get the latest and greatest code. The following comands switch to this branch and apply our patch:
nexus-s $ cd gaia
nexus-s/gaia $ git checkout -b nexus-s mozillaorg/master
nexus-s/gaia $ curl -k -L https://bug869289.bugzilla.mozilla.org/attachment.cgi?id=746196 >p1.patch
nexus-s/gaia $ patch -p1 <p1.patch
nexus-s/gaia $ git commit -a -m "Nexus S video app thumbnail fix"
There is a bug related to video recording on the Nexus S. To fix this we need a patch from bug 832638:
To apply this:
nexus-s/gaia $ curl -k -L https://bugzilla.mozilla.org/attachment.cgi?id=704241 >p2.patch
nexus-s/gaia $ patch -p1 <p2.patch
nexus-s/gaia $ git commit -a -m "Nexus S video recording fix"
Building
Now that all the required changes have been made we can build:
nexus-s $ ./build.sh
Installing
Once the build is complete you should be able to flash the Nexus S with the results. Note that this completely wipes everything on your phone:
nexus-s $ ./flash.sh
The phone should reboot after this step with Firefox OS installed and prompting for information from the "First Run" app.
New Zealand changes
Some New Zealand sites don't detect Firefox OS and serve their mobile versions. This can be changed by adding overrides to gaia/build/ua-override-prefs.js. I add the entries in b2gnzuaoverride.txt to this file to get stuff.co.nz, mega.co.nz and trademe.co.nz serving the correct mobile site. Once added to this file, reinstall Gaia on the phone.
nexus-s $ ./flash.sh gaia
Updating
To update the source to latest versions we need to 'rebase' our changes on top of the most recent repository changes. The following steps will do this:
nexus-s $ git pull
nexus-s $ ./config.sh nexus-s
nexus-s $ cd gecko
nexus-s/gecko $ git rebase m/v1-train
nexus-s/gecko $ cd ../gaia
nexus-s/gaia $ git rebase mozillaorg/master
nexus-s/gaia $ cd ..
nexus-s $ ./build.sh
You may need to do some fixing up of merge conflicts if changes have occurred to the areas we've patched.
To flash the phone, overwriting everything on it, including all user data:
nexus-s $ ./flash.sh
To flash the phone, keeping (most of...) your existing user data:
nexus-s $ ./flash.sh system
nexus-s $ ./flash.sh gecko
nexus-s $ ./flash.sh gaia
Note that flashing gaia might remove some of your installed application icons. You'll need to reinstall those apps to fix that.
