B2G OS build prerequisites

Compatible build targets

You need a compatible device to build for, or you can use an emulator.

Emulator

There are two emulators available: one emulates ARM code and the other runs everything in x86 code. Learn more about installing and using the emulators. Do not use the x86 emulator — it is hard to install and not as compatible.

Desktop

You can build a desktop version of B2G OS; this runs Gecko in a XULRunner application, and you then use the Gaia user experience inside it.

Devices

Several devices are compatible with B2G OS, but some are more compatible than others, and only specific variants of a device may be compatible. Check the compatible devices page for more details.

Requirements for GNU/Linux

To build on Linux, you'll need:

• A 64 bit GNU/Linux distribution (Ubuntu 14.04 LTS recommended).
• At least 4 GB of RAM.
• At least 40 GB of available hard disk space.

You will also need the following tools installed:

Ubuntu 12.04 LTS / Debian 6 / Linux Mint 13

Run the following command in Terminal:

sudo apt-get install autoconf2.13 bison bzip2 ccache curl flex gawk gcc g++ g++-multilib git ia32-libs lib32ncurses5-dev lib32z1-dev libasound-dev libgconf2-dev libgl1-mesa-dev libx11-dev lzop make zip libxml2-utils nodejs unzip python

you can install the jdk via this ppa.

Ubuntu 14.04 LTS / Debian 7

First, run the following commands to set the required architectures:

sudo dpkg --add-architecture i386
sudo dpkg --add-architecture amd64

Then, run the following command in Terminal:

sudo apt-get install --no-install-recommends autoconf2.13 bison bzip2 ccache curl flex gawk gcc g++ g++-multilib git lib32ncurses5-dev lib32z1-dev libgconf2-dev zlib1g:amd64 zlib1g-dev:amd64 zlib1g:i386 zlib1g-dev:i386 libgl1-mesa-dev libx11-dev make zip lzop libxml2-utils openjdk-7-jdk nodejs unzip python libxt6

Ubuntu 16.04

sudo apt-get install make=3.81-8.2ubuntu3

sudo apt-mark hold make 

First, run the following commands to set the required architectures:

sudo dpkg --add-architecture i386
sudo dpkg --add-architecture amd64

Then, run the following command in Terminal:

sudo apt-get install --no-install-recommends autoconf2.13 bison bzip2 ccache curl flex gawk gcc g++ g++-multilib git lib32ncurses5-dev lib32z1-dev libgconf2-dev zlib1g:amd64 zlib1g-dev:amd64 zlib1g:i386 zlib1g-dev:i386 libgl1-mesa-dev libx11-dev make zip lzop libxml2-utils openjdk-8-jdk nodejs unzip python

Ubuntu 16.10

On ubuntu 16.10 the default make version is 4.1 which prevents you from building android, to correct this issue enter the following commands into the console:

wget http://ftp.us.debian.org/debian/pool/main/m/make-dfsg/make_3.81-8.2_amd64.deb
sudo dpkg -i make_3.81-8.2_amd64.deb

Then to avoid automatic upgrade you can mark has hold on the make package:

sudo apt-mark hold make

Next you need to add the requited architectures:

sudo dpkg --add-architecture i386
sudo dpkg --add-architecture amd64 

Then, run the following command in Terminal:

sudo apt-get install --no-install-recommends autoconf2.13 bison bzip2 ccache curl flex gawk gcc g++ g++-multilib git lib32ncurses5-dev lib32z1-dev libgconf2-dev zlib1g:amd64 zlib1g-dev:amd64 zlib1g:i386 zlib1g-dev:i386 libgl1-mesa-dev libx11-dev make zip lzop libxml2-utils openjdk-8-jdk nodejs unzip python 

Configure USB access

On Linux systems a regular user can't directly access USB devices by default. You need to configure udev rules. Create a file at /etc/udev/rules.d/51-android.rules with the following command:

TODO: Merge Bug 1230463

wget -S -O - https://raw.githubusercontent.com/cm-b2g/B2G/1230463/tools/51-android.rules | sudo tee >/dev/null /etc/udev/rules.d/51-android.rules; sudo udevadm control --reload-rules
wget -S -O - https://raw.githubusercontent.com/mozilla-b2g/B2G/master/tools/51-android.rules | sudo tee >/dev/null /etc/udev/rules.d/51-android.rules; sudo udevadm control --reload-rules

The new rules take effect the next time a device is plugged in.

Configure ccache

We build a lot of code but the majority of that code does not change between builds. We can dramatically speed up build with the ccache compilation tool. Give it a 50GB cache with the following command:

ccache -M 50G

Alternative Distros

Fedora 22

Run the following command in 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 lzop libxml2-utils

Arch Linux

Run the following command in 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 lzop

To install the lib32-* packages you need to have the multilib repository enabled.

By default, Arch Linux uses Python 3. You'll have to force it to use the old Python 2. You can do that by linking the python2 executable to python but this is discouraged and considered error-prone. This will also break Python 3 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

So that executing

python --version

Gives as result "Python 2.7.12".

Gentoo Linux

Installing ccache

You will 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, on the subsequent step of this guide where the ./build.sh script is called, Gentoo users should instead run the command with an explicitly extended path, ie.

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

Generating Partition Images

If you are building B2G for actual physical hardware, then you may at some point also wish to generate some partition images for upload to your device. (For example, to restore backed up files to the device via the fastboot utility)

The filesystem image format used in this case is YAFFS2 (Yet Another Filesystem 2). Gentoo has support for the very latest (ie. git HEAD) yaffs2-utils userland package in portage. (Note: You will also need kernel patches if you want to mount YAFFS2 images, but this is not really required since you can deconstruct and rebuild them instead.)

# emerge --autounmask-write yaffs2-utils; etc-update; emerge -av yaffs2-utils

In order to generate such an image, simply change to the parent directory of the partition filesystem tree you wish to package, and issue a command like this:

mkyaffs2image system/ system.img

Legacy branches

If you need to compile an older branch of B2G OS you may hit build errors. See the building legacy branches page.

Requirements for OS X

Building B2G OS on OS X is possible, but it is not easy, nor is it well supported. You will need to install an old version of Xcode which may interfere with the current version if you are already using it. For the best experience you should build on Ubuntu 14.04 LTS. However if you insist try these steps:

OS X 10.11 El Capitan & OS X 10.10 Yosemite

Case sensitive file system

The default installation of OS X is unsuitable to build B2G OS. You will need to re-install OS X on a case sensitive file system.

Xcode 7.2

1. Install the latest Xcode from the Apple Store.
2. Accept the licence with the following command:

sudo xcodebuild -license

Xcode Command Line Tools

Install the Xcode Command Line Tools with the following command:

xcode-select --install

Xcode 5.1.1

AOSP, and therefore B2G OS, is not compatible with the latest version of the Xcode SDK. We need an older version installed alongside the latest version.

1. Download Xcode 5.1.1 from developer.apple.com and install it to /Applications/Xcode-5.1.1
2. Switch to using the Xcode 5.1.1 SDK with the following command:

sudo xcode-select --switch "/Applications/Xcode-5.1.1/Xcode.app/Contents/Developer"

Java SE Development Kit 7

AOSP, and therefore B2G OS, is not compatible with the Java JDK v8 so we need to install the Java JDK v7. You can download it from http://www.oracle.com/.

Bash Profile

Add the following to your ~/.bash_profile file:

export PATH=~/bin:$PATH
export PATH=/usr/local/bin:$PATH
export BUILD_MAC_SDK_EXPERIMENTAL=1
export LC_CTYPE=C
export LANG=C
export USE_CCACHE=1

Homebrew

We need to install some more command line tools not provided by Apple. Install Homebrew:

ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Next, install the tools with the following command:

brew install ccache coreutils cmake findutils git gnu-tar gnu-sed gpg lzop yasm

We need a specific version of autoconf, version 2.13:

brew install homebrew/versions/autoconf213

Configure ccache

We build a lot of code but the majority of that code does not change between builds. We can dramatically speed up build with the ccache compilation tool. Give it a 50GB cache with the following command:

prebuilts/misc/darwin-x86/ccache/ccache -M 50G

Legacy instructions for OS X

Run B2G OS Mac Bootstrap

Next, open a terminal and run the following command:

curl -fsSL https://raw.github.com/mozilla-b2g/B2G/master/scripts/bootstrap-mac.sh | bash

This will pull and run a bootstrap script that makes sure you have all the prerequisites met to build the emulator. It will also prompt you for permission to install anything you're missing, and provide warnings and suggested fixes to problems.

To Delevop with B2G you will need to fetch a special branch. That will be loaded from the Mercurial. (learn more) As OSX doesn't have Mercurial installed by default you need to install it with this code:

$ brew install mercurial

Be aware of Mac file system case sensitivity

By default, OS X ships with a case-insensitive file system. This is problematic because the Linux kernel has a number of files with the same name, but different case. For example, see the header files xt_CONNMARK.h and xt_connmark.h This results in a number of files appearing to be modified in /kernel after a fresh ./config.sh.

In many cases you can run the build just fine; for some platforms, however, you may encounter the following error:

ERROR: You have uncommited changes in kernel
You may force overwriting these changes
with |source build/envsetup.sh force|
ERROR: Patching of kernel/ failed.

Please see bug 867259 for more discussion and possible fixes for this problem.

Alternatively, it will always be safest to build on a case sensitive file system.  The easiest way to do this is to create a separate, mountable disk image with case-sensitivity enabled.  Be aware that if you change the name of -volname to not use capital letters. You can do this using Apple's Disk Utility application or from the command line:

hdiutil create -volname 'firefoxos' -type SPARSE -fs 'Case-sensitive Journaled HFS+' -size 80g ~/firefoxos.sparseimage

Mount the drive with:

open ~/firefoxos.sparseimage

Change into the mounted drive with:

cd /Volumes/firefoxos/

You can then check out the code and compile from this location without worrying about case-sensitivity problems.

Optional: Install HAX

Intel provides a special driver that lets the B2G emulator run its code natively on your Mac instead of being emulated, when you're using the x86 emulator. If you wish to use this, you can download and install it. It's not required, but it can improve emulation performance and stability.  

Before you install HAX you will need to install the Android SDK.

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. Our Installing ADB article explains how to get adb installed.

Follow Samsung Galaxy S2 extra steps

If you plan to build for the Samsung Galaxy S2, you will also need to install heimdall. See Installing heimdall for details. This is not done for you by the bootstrap script!

In addition, you should also keep the following points in mind:

1. When you eventually come to install your build on an S2 device, before running the flash.sh script you need to change all instances of factoryfs to FACTORYFS, as well as kernel to KERNEL (check your pit output to confirm), otherwise it won't work.
2. The Siyah-s2 Recovery ROM works best. CWM works ok as well, but there are a few issues.
3. Flashing your S2 using flash.sh will get the base OS working ok, but Gaia may have problems out of the box. Refreshing it with make reset-gaia PRODUCTION=1 should clear up such issues.

Install heimdall

Heimdall is a utility for flashing the Samsung Galaxy S2. It's used by the Boot to Gecko flash utility to replace the contents of the phone with B2G OS, as well as to flash updated versions of B2G and Gaia onto the device. You'll need it if you want to install B2G 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 GitHub and build it yourself.
• Use a package manager to install it.
  • On Linux: sudo apt-get install libusb-1.0-0 libusb-1.0-0-dev
  • On Mac, you can download an installer package and use that.

On to the next step

At this point, you should be ready to fetch the B2G OS code!