An Introduction to Firefox OS

Firefox OS (project name: Boot to Gecko, also known as B2G) is a Linux kernel-based open source operating system for smartphones and tablet computers. It is being developed by Mozilla, the non-profit organisation best known for its Firefox Web browser. The Firefox OS is about pushing the boundaries of what is possible with the Web on the mobile, and enabling entirely new segments of users to come online with their first smartphones.

The Firefox OS is designed to provide a complete community-based alternative system for mobile devices, using open standards and approaches such as HTML 5 applications, JavaScript, a robust privilege model, open Web APIs to communicate directly with cell phone hardware and an application marketplace.

Firefox OS terminology
There are a few terms that we need to get used to before we go further with the Firefox OS.

B2G: This is the short form for ‘Boot 2 Gecko’. This is the main engine on which the Firefox OS runs and is the engineering code name for the Firefox OS. You will often see this term used to refer to the Firefox OS, since it was used for a long time before the project had an official name.

Firefox OS: Firefox OS is basically Mozilla’s branding and support services applied on top of the B2G, to create a final release product.
Gaia: This is the user interface of the Firefox OS platform. Gaia implements the lock screen, home screen and all the standard applications you expect on a modern smartphone. It is implemented entirely using HTML, CSS and JavaScript. Its only interfaces to the underlying operating system are through Web APIs that are implemented by the Gecko layer. Third party applications can be installed alongside the Gaia layer.

Gecko: This is the Firefox OS application runtime, i.e., this layer provides all the support for the triad of open standards—HTML, CSS and JavaScript. It makes sure these APIs work well on every operating system Gecko supports. This means that Gecko includes, among other things, a networking stack, graphics stack, layout engine, a JavaScript virtual machine and porting layers.

Gonk: Gonk is the lower level operating system of the Firefox OS platforms, consisting of a Linux kernel and user space hardware abstraction layer (HAL). The kernel and several of the user space libraries are common open source projects: Linux, libbus, Bluez, etc. Some of the parts of the HAL are shared with the AOSP (Android Open Source Project), such as GPS, camera and others. You could say that Gonk is a very simple Linux distribution. It is a porting target of Gecko, i.e., there’s a port of Gecko to Gonk, just like there’s a port of Gecko to OS-X, Windows and Android. Since the Firefox OS project has full control over Gonk, we can expose interfaces to Gecko that can’t be exposed on other operating systems.

Jank: This term is often used in the mobile apps space, and refers to the effect of slow or inefficient code operations in an app, which block the updating of the UI and cause it to lag or become unresponsive.

Firefox OS build prerequisites
Here is a small guide on how to build the Boot 2 Gecko project’s source code.
Requirements for GNU/Linux
To build the B2G project source code on Linux, you need the following minimum requirements:

• A 64-bit GNU/Linux distribution
• At least 4GB RAM
• Free hard disk space of 30GB

This is more than the bare minimum requirements, but sometimes the build might fail just because of some missing resources. A typical error in this case is ‘arm-linux-androideabi-g++: Internal error: Killed (program cc1plus)’.
You will also need the following tools installed in the system before you start the build process:

autoconf 2.13, bison, bzip2, ccache, curl, flex, gawk, git, gcc / g++ / g++-multilib, java sdk (jdk), make, OpenGL shared libraries, patch, X11 headers, 32-bit ncurses, 32-bit zlib

Requirements for 64-bit installation
Ubuntu/Linux Mint: Run the following commands in a terminal:

sudo apt-get update
sudo apt-get install autoconf2.13 bison bzip2 ccache curl flex gawk gcc g++ g++-multilib git ia32-libs lib32ncurses5-dev lib32z1-dev libgl1-mesa-dev libx11-dev make zip

If you are building for the Flame reference phone or for Nexus 5, run the following command in a terminal:

Sudo apt-get install libxml2-utils

In addition to the emulator build issues discussed above, the compiler will default to gcc-4.7, which will fail to build due to an error along the following lines:

“KeyedVector.h:193:31: error: indexOfKey was not declared in this scope, and no declarations were found by argument-dependent lookup at the point of instantiation”

In a fresh Ubuntu 12.10 install, you’ll get an error about unmet dependencies for ia32-libs. The following commands fix it:

sudo dpkg –add architecture i386
sudo apt-get update
sudo apt-get install ia32-libs

Fedora 19/20: Those using Fedora 19/20 can type the following commands in a terminal:

sudo yum install autoconf213 bison bzip2 ccache curl flex gawk gcc-c++ git glibc-devel glibc-static libstdc++-static libX11-devel make mesa-libGL-devel ncurses-devel patch zlib-devel ncurses-devel.i686 readline-devel.i686 zlib-devel.i686 libX11-devel.i686 mesa-libGL-devel.i686 glibc-devel.i686 libstdc++.i686 libXrandr.i686 zip perl-Digest-SHA wget

The project should build correctly using the default compiler shipped with Fedora but if you encounter compilation errors, you might need to install GCC 4.6.x:

Download the tarball and then install it to /opt with the following command on Fedora 19/20:

curl url -O http://people.mozilla.org/~gsvelto/gcc-4.6.4-fc19.tar.xz
sudo tar -x -a -C /opt -f gcc-4.6.4-fc19.tar.xz

Arch Linux: To install the required resources in Arch Linux, run the following command in the terminal:

sudo pacman -S --needed alsa-lib autoconf2.13 bison ccache curl firefox flex gcc-multilib git gperf libnotify libxt libx11 mesa multilib-devel wget wireless_tools yasm zip lib32-mesa lib32-mesa-libgl lib32-ncurses lib32-readline lib32-zlib

B2G can be only compiled with gcc4.6.4, and because Arch Linux always has bleeding edge software, you will need to install gcc46–multilib from AUR. Remember that you will have to edit the PKGBUILD and add staticlibs to the options array, or gcc will be unable to compile B2G and give you a ‘cannot find –lgcc’ error when compiling. You will also need to add the following to your .userconfig file:

export CC=gcc-4.6.4
export CXX=g++-4.6.4

By default, Arch Linux uses Python3. You’ll have to force it to use the old Python2. You can do that by linking the Python2 executable to Python, but this is discouraged since it is considered error-prone. This will also break Python3 if it is installed on your system. A better way is to use virtualenv/virtualenvwrapper:

sudo pacman –S python-virtualenvwrapper
source /usr/bin/virtualenvwrapper.sh
mkvirtualenv –p ‘which python2’ firefoxos
workon firefoxos

Android will complain that you need make 3.81 or make 3.82 instead of 4.0. You can download make 2.81 from AUR. This will install the make-3.81 binary on your path; you need to create a symlink named make by retaining the same location as mentioned in the PATH variable for the build to use the correct version:

mkdir –p ~/bin
ln –s ‘which make-3.81’ ~/bin/make
export PATH=~/bin:$PATH

Android also needs the Java6 SDK, and Arch only has Java7.  Unfortunately, the AUR build is broken, but you can still download the Java6 SDK and install it manually. You will then need to put it in your path.

cp ~/Downloads/jdk-6u45-linux-x64.bin/opt
su
cd /opt
chmod +x jdk-6u45-linux-x64.bin
./jdk-6u45-linux-x64.bin
exit
ln -s /opt/jdk1.6.0_45/bin/java ~/bin/java

Gentoo Linux: You need to install ccache, a tool for caching partial builds:

emerge –av ccache

Because ccache is known to frequently cause support issues, Gentoo encourages you to use it explicitly and sparingly.
To enable the required use of ccache, in the subsequent step of this guide in which the ./build.shscript is called, Gentoo users should instead run the command with an explicitly extended path, i.e.:

PATH =/usr/lib64/ccache/bin:$PATH ./build.sh

Install ADB
The build process needs to pull binary blobs from the Android installation on the phone before building B2G (unless you’re building the emulator, of course).  For this, you will need ADB, the Android Debug Bridge.
Note: Remember that when you start to use ADB, the phone’s lock screen will need to be unlocked to view your phone’s contents (at least in later versions of the Firefox OS). You’ll probably want to disable the lock screen (we’ll get to that later in the build instructions).

Install Heimdall
Heimdall is a utility for flashing the Samsung Galaxy S2. It’s used by the B2G flash utility to replace the contents of the phone with Firefox OS, as well as to flash updated versions of B2G and Gaia onto the device. You’ll need it if you want to install Firefox OS on a Galaxy S2; it is not needed for any other device. For other devices, we build and use the fastboot utility instead.
There are two ways to install Heimdall:

• You can download the code from Github and build it yourself
• Use the package manager to install Heimdall
• Run the following command in the terminal: “sudo apt-get install libusb-1.0-0 libusb-1.0-0-dev”

Configuring ccache
The B2G build process uses ccache. The default cache size for ccache is 1GB, but the B2G build easily saturates this; so around 10GB is recommended. You can configure your cache by running the following command inside the terminal:

ccache –max-size 10GB

Enabling remote debugging
Before you plug your phone back into your USB port, put it in USB developer mode. This allows you to debug and flash the phone. To enable developer mode, enable Remote Debugging in Developer Settings. Once the option is checked, remote debugging is enabled, and you are ready to go.
At this point, connect your phone to your computer via a USB cable (if you created the udev rule earlier, this will trigger udev to detect the phone and create the device node with the right permissions). You can now check if you can list your device via the ADB devices command (remember that ADB can only see your phone when the lock screen is unlocked). If everything has worked well, you should see an output similar to the following (which is for a Geeksphone Keon):

$ adb devices
List of devices attached
Full_keon device

Building Firefox OS
Depending on your Internet connection, the configuration takes a number of hours to download the files necessary to build Firefox OS (with a slow 150kbps connection, downloading gigabytes of Android repositories can take tens of hours).  Waiting is not as much fun as actually doing something, so after you have read through this page and have kicked off the configure script, consider using the time to set up and try out the Firefox OS simulator. Begin familiarising yourself with ‘Documentation for app developers’ including ‘Designing and Building an App’. You could also read up on information related to the upcoming steps.

Cloning the B2G repository
The first step, before you can start your first build, is to clone the B2G repository. This will not fetch everything! Instead, it will fetch the B2G build system and set-up utilities. Most of the actual B2G code is in the main Mozilla Mercurial repository.
To clone this repository, use Git and run the following commands in the terminal:

git clone git://github.com/mozilla-b2g/B2G/git
cd B2G

Once you’ve retrieved the core B2G build system, you need to configure it for the device on which you plan to install it. To get a list of supported devices, you can use the config.sh utility; run the following command from within the B2G directory:

./config.sh

When you enter the above command, you will get something like the following in the terminal screen:

Usage: ./config.sh [-cdflnq] (device name)
Flags are passed through to |./repo sync|

Valid devices to configure are:
- galaxy-s2
- galaxy-s2
- nexus-4
- nexus-s
- nexus-s-4g
- flo “(Nexus 7 2013)”
- nexus-5
- flame
- otoro
- unagi
- inari
- keon
- peak
- leo
- hamachi
- helix
- wasabi
- fugu
- tara
- pandaboard
- emulator
- emulator -jb
- emulator -kk
- emulator -x86
- emulator -x86-jb
- emulator -x86-kk

Now, depending on the device you are working on, you can just build the emulator for it. For example, when you want to build the emulator for a Nexus device, you need to run the following command in the terminal:

./config nexus

Updating your B2G tree
When the repository is updated to a newer version of B2G, you’ll want to update your B2G tree. To do this, you can run the following commands in the terminal:

git fetch origin
git checkout origin/master

You can check that these worked correctly by running the following command:

git show HEAD

Starting the build process
Updating your code
If this isn’t your very first time building B2G, you might want to pull the latest code before you start to build. To do that, you should update both the B2G tools and the dependencies, using the following two commands:

git pull
./repo sync -d

The -d option switches the various projects’ HEAD back to their Android manifest revision (i.e., the default mainstream repository version). This is helpful if you made modifications to the repos (and have associated source changes) but want to revert back to the master version temporarily. It will leave your staged or working directory changes untouched.
Building the B2G tree
To start the build process, run the following command in the terminal inside the B2G folder:

./build.sh

It will take around one hour or more to build the B2Ge source code locally. Once you are done building the source code, you can start the emulator by running the following command in the terminal in the B2G folder itself:

./run-emulator.sh

Submitting bug reports on B2G, Firefox OS and Gaia
Once you’ve got a B2G/Firefox OS build running, you’ll probably want to start to file bug reports against this specific version, so that the Firefox OS community can improve things as effectively as possible. You’ll need to file the bug on Bugzilla, under the ‘Firefox OS’ project, but you should include specifics about the version:

• To start with, give the major version number, e.g., 1.4.0.0-pre-release. This can be found on the device under Settings > Device Information
• You can provide more specific version identifiers by returning the current hashes from the Gaia and Gecko repositories. This can be done as follows:

#!/bin/bash
(cd gaia; echo “gaia $(git rev-parse HEAD)”)
(cd gecko; echo “gecko $(git rev-parse HEAD)”)

After making some changes in the B2G tree, you need to push them to the master tree, which is based on Git.

References
[1] https://developer.mozilla.org/en-US/Firefox_OS/