Firefox OS build prerequisites

  • Revision slug: Mozilla/Firefox_OS/Firefox_OS_build_prerequisites
  • Revision title: Firefox OS build prerequisites
  • Revision id: 487169
  • Created:
  • Creator: icarot
  • Is current revision? No
  • Comment

Revision Content

Before obtaining the code to build Firefox OS, you need a properly configured build system. You can currently build on 64-bit Linux distributions and OS X.

Note: To build Firefox OS onto a phone, begin with your phone NOT connected to your computer. We'll tell you when to plug it in.

Have a compatible device/emulator

You need to have a compatible device to build onto, or to use an emulator. Though we support several phones, some have multiple variations. We currently support specific variations and some devices have better support than others:

Tier 1

Tier 1 devices represent a primary target for development and will typically be the first to receive bug fixes and feature updates.

Keon
Keon is the Geeksphone Keon device, which is one of the initial developer phones. Note that builds for this device are provided by Geeksphone.
Inari
Inari is another testing device. Use this configuration to build for the ZTE Open device.
Unagi
Unagi is a phone being used as a test and development platform as a low-to-midrange smartphone. Many core Firefox OS developers are working on Unagi.
Otoro
Otoro is a phone being used as a test and development platform as a low-to-midrange smartphone. Many core Firefox OS developers are working on Otoro.
Pandaboard
The Pandaboard is a development board based on the OMAP 4 architecture, used to do development work on mobile platforms.
Emulator (ARM and x86)
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.
Note that you shouldn't use the x86 emulator — it is hard to install and not well supported.
Desktop
You can also build a desktop version of Firefox OS; this runs Gecko in a XULRunner application, and you then use the Gaia user experience inside it.

You can, of course, build the desktop client or one of the emulators without a phone.

Tier 2

Tier 2 devices are generally functional and many developers (especially app developers) are using them, so they tend to pick up changes secondarily.

Samsung Nexus S
The known working model numbers of Nexus S devices are GT-I9020A and GT-I9023. Others may work.
Samsung Nexus S 4G
The SPH-D720 is supported as a tier 2 device.

Tier 3

Firefox OS can be built for these devices, but they are not being actively worked on a regular basis by core developers. Their reliability and feature set may lag noticeably behind tier 1 and even tier 2 devices.

Samsung Galaxy S2
The only model that works is the i9100; no other variants are officially compatible. (i9100P might work, since the only change is a NFC chip added)
Samsung Galaxy Nexus
We are not currently aware of any variations that are not compatible.
Tara
Tara is another testing device. Manifest of Tara is in master branch only. The script of getting Tara code is "BRANCH=master ./config.sh tara".
Important: Only devices running at least Android 4 (aka Ice Cream Sandwich) are supported. If your device is listed above but running an older version of Android, please update it before doing anything.

Note: Tier 2 and Tier 3 devices have a software home button instead of a hardware home button

All Tier 1 devices have a hardware Home button which returns the user to the home screen. Most current ICS based Android devices use onscreen touch buttons for navigation. We have a virtual home button for the devices without hardware home button now. If it's not automatically enabled, open the Settings app and navigate down through Device Information -> More Information -> Developer, then toggle on the "Enable software home button" preference.

Requirements for Linux

To build on Linux, you'll need:

  • A 64 bit GNU/Linux distribution (Ubuntu 12.04 recommended).
  • At least 4 GB of RAM/swap space.
  • At least 20 GB of available hard disk space.

This is more than the bare minimum, but sometimes building fails just because it's missing resources.

You will also need the following tools installed:

  • autoconf 2.13
  • bison
  • bzip2
  • ccache
  • curl
  • flex
  • gawk
  • git
  • gcc / g++ / g++-multilib
  • make
  • OpenGL shared libraries
  • patch
  • X11 headers
  • 32-bit ncurses
  • 32-bit zlib

Emulator build issues

If you are making an emulator build, you need to pay attention to these issues:

First, note that you shouldn't use the x86 emulator — it is hard to install and not well supported.

Next, the build-system for the emulator builds both 32bit and 64bit versions of the emulator. As the emulator depends on OpenGL, this means that you need to have both 32bit and 64bit versions of OpenGL libraries installed on your system. See the discussion in bug bug 897727.

There are two ways that you can solve this problem:

If your linux distro has multilib packages for OpenGL libraries, you can attempt installing them. You might then have to manually create some symlinks.

For example, here is the situation on Ubuntu 12.04 LTS x86-64. On this distribution, the libgl1-mesa-dev package cannot be installed simultaneously in x86-64 and i386 versions, but you can have the following combination of packages simultaneously installed:

sudo apt-get install libgl1-mesa-dev libglapi-mesa:i386 libgl1-mesa-glx:i386

After having run this command, you will still have to manually create some symlinks for the emulator build to succeed:

$ sudo ln -s /usr/lib/i386-linux-gnu/libX11.so.6 /usr/lib/i386-linux-gnu/libX11.so
$ sudo ln -s /usr/lib/i386-linux-gnu/mesa/libGL.so.1 /usr/lib/i386-linux-gnu/libGL.so

Solution #2: just patch the emulator so it only builds 64bit

Just apply this patch to the sdk/ git repository under the B2G repo. This will cause the B2G emulator to only attempt to build the 64bit emulator if you're on a 64bit system, thus avoiding any multilib issues. The 32bit emulator is unused anyway on a 64bit system. This is the simplest solution... until this patch eventually bit-rots.

64 bit requirement installation

This section lists the commands you need to run in different Linux distributions to install at the requirements for building Firefox OS.

Ubuntu 12.04 / Linux Mint 13 / Debian 6

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

And see the above comments about emulator build issues!

Ubuntu 12.10

Run the following command in Terminal:

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

In addition to the emulator build issues discussed above, the compiler will default to gcc-4.7, which will fail to build with 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"

To fix this, you will need to specify GCC 4.6 as the default host compiler after having retrieved the B2G sources: Read Changing the default host compiler to find out how to do it.

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

Ubuntu 13.04

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 gcc-4.6 g++-4.6 g++-4.6-multilib git ia32-libs lib32ncurses5-dev lib32z1-dev zlib1g:amd64 zlib1g-dev:amd64 zlib1g:i386 zlib1g-dev:i386 libgl1-mesa-dev libx11-dev make zip

In addition to the emulator build issues discussed above, the compiler will default to gcc-4.7, which will fail to build with 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"

To fix this, you will need to specify GCC 4.6 as the default host compiler after having retrieved the B2G sources: Read Changing the default host compiler to find out how to do it.

Ubuntu 13.10

With Ubuntu 13.10, multi-arch packages are now the main way to support multiple architectures (e.g. 32-bit on a 64-bit install).  You must tell your Ubuntu system that you want to support 32-bit packages as well:

sudo dpkg --add-architecture i386
sudo apt-get update

Once you've completed that, then you can install the necessary packages:

sudo apt-get install --no-install-recommends autoconf2.13 bison bzip2 ccache curl flex gawk gcc g++ g++-multilib gcc-4.6 g++-4.6 g++-4.6-multilib git lib32ncurses5-dev lib32z1-dev zlib1g:amd64 zlib1g-dev:amd64 zlib1g:i386 zlib1g-dev:i386 libgl1-mesa-dev libx11-dev make zip

Fedora 17/18/19

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

In addition to the above you will need GCC 4.6.x in order to compile the project:

Download the right version for your Fedora installation, then install it to /opt, with the following command on Fedora 17/18:

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

And with the following command for Fedora 19:

$ curl -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

You will need to specify GCC 4.6.x as the default host compiler after having retrieved the B2G sources: Read Changing the default host compiler to find out how to do it.

If build fails with the compiler complaining about not finding libmpc.so.2, install the package compat-libmpc

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

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

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 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

Requirements for Mac OS X

To build Firefox OS on Mac OS X, there are a number of prequisite steps you need to follow, which are detailed below. We also discuss common errors you might come across in particular situations, and solutions to those.

Note: Configuring and Building B2G for Keon WON'T WORK on a Mac. You'll need to use Linux to build B2G for this device.

Install XCode Command Line Utilities

You need to install Xcode's Command Line Utilities. You can download just the Command Line Utilities from Apple's developer downloads page for your particular version of OS X, however if you would like the entire Xcode suite of applications, you can install Xcode through the Mac App Store. 

Xcode 4.3.1 (OS X 10.7 "Lion") and other newer versions such as 4.4.1+ (that is, Mac OS X10.8 "Mountain Lion"), won't necessarily include the required Command Line Utilities. When you install Xcode, make sure to go into Preferences, then the Downloads panel, and install the Command Line Utilities. In addition, make sure you have at least 20 GB of free disk space.

Screenshot of Xcode Downloads Command Line Tools

Note: The Firefox OS emulator requires a Core 2 Duo processor or later; that is, a system that is compatible with Mac OS X 10.7 "Lion." You do not actually have to be running Lion, you just have to be compatible with it. You can, however, build any Firefox OS build on many older Macs.

Run Firefox 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. The script will check for and install the following items:

  • git
  • gpg
  • ccache
  • yasm
  • autoconf-213
  • gcc-4.6
  • homebrew

Xcode wrangling

If you have already upgraded to Xcode 4.4+ and get the message that Xcode is outdated, check the Xcode path with:

xcode-select -print-path

If it still points to /Developer you can update the path with:

sudo xcode-select -switch /Applications/Xcode.app

Making the Mac OS X 10.6 SDK available

You also need to have the Mac OS X 10.6 SDK available. The SDK needs to be available at

/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/

If it cannot be found there you will need to extract and copy it from Xcode 4.3. To do this:

  1. Download the XCode 4.3 .dmg file from the Apple Developer portal (you'll need an Apple Developer account).
  2. Download the utility Pacifist and use it to extract the 10.6 SDK from the XCode 4.3 .dmg file. Click on the "Extract Package" button, find the SDK by searching for 10.6 in the search box, then Ctrl + click on the MacOSX10.6.sdk directory and Extract it to a suitable location.
  3. Add a symlink from the 10.6 SDK location to the /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/ directory. For example, if you put the 10.6 SDK on your desktop, the comment would be
ln -s /Users/<yourusername>/Desktop/MacOSX10.6.sdk /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/

Note: We can drop the 10.6 SDK requirement after bug 784227 has been fixed, and our version of platform_build has been updated.

Be aware of Mac file system case sensitivity

By default, Mac 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.  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 40g ~/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.

Mountain Lion homebrew gotcha

If you are on Mountain Lion and you receive an error during the installation of the dependencies via homebrew, such as:
clang: error: unable to execute command: Segmentation fault: 11
... try reinstalling the dependency manually adding the --use-gcc flag, for example:
brew install mpfr --use-gcc

Follow Samsung Galaxy S2 extra steps

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

Note: If you have installed the Samsung Kies tool, which is used to manage the contents of many Samsung phones, you will have to remove it before you can flash Firefox OS onto your device. You can use the standard application removal process on Windows; on Mac, the Kies install disk image has a utility to fully remove Kies from your system. Flashing will not work if you have Kies installed. If you forget to remove Kies, the build system will detect it and remind you to uninstall it. Note also that the uninstall tool does not correctly remove the folder ~/Library/Application Support/.FUS, and leaves a reference to a utility there in your user startup items list. You will want to remove these manually.

Fix libmpc dependency if broken

gcc 4.6 was built with libmpc 0.9; if you then use homebrew to update packages, libmpc gets updated to version 1.0, but homebrew doesn't rebuild gcc 4.6 after the library version changes. So you need to create a symlink to make things work again, like this:

cd /usr/local/lib/
ln -s libmpc.3.dylib libmpc.2.dylib

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.

You can download and install adb as part of the Android SDK package, for Mac, Linux or Windows - visit the Get the Android SDK page.

Newer Linux distributions have adb already in their repositories. For Ubuntu 12.10 and later, run the following command:

sudo apt-get install android-tools-adb

Or for Fedora 18/19:

sudo yum install android-tools

If your distribution does not have packages for adb available (i.e. Ubuntu 12.04 or Fedora 17), you'll need to install the Android SDK starter package for your platform (you'll want the ADT Bundle, not the SDK Tools Only option). Then run their package manager, $SDK_HOME/tools/android, and use the GUI to install "Android SDK Platform-tools".

Find out where adb is installed (usually in usr/bin, possibly additionally inside adt/platform-tools, depending on how you installed it). Be sure to add this directory to your PATH. This can be done by adding the line

PATH=$SDK_HOME:$PATH

replacing $SDK_HOME with the location of the android sdk, to your ~/.bashrc or equivalent.

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 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.

Note: Again, it's important to note that this is only required for installing Firefox OS on the Samsung Galaxy S2.

There are two ways to install heimdall:

Configure ccache

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

$ ccache --max-size 3GB

For Linux: configure the udev rule for your phone

Note: This section is specific to Linux; Mac OSX has the necessary device permissions set up already.

Next, you need to confingure the udev rule for your phone,

You can get the USB vendor ID by running lsusb with your phone plugged in, but typically it's Google 18d1, Samsung 04e8, ZTE 19d2, Geeksphone/Qualcomm 05c6. Add this line in your /etc/udev/rules.d/android.rules file (replacing XXXX with the ID for your device):

SUBSYSTEM=="usb", ATTR{idVendor}=="XXXX", MODE="0666", GROUP="plugdev"

Take ZTE for example, the content in android.rules will be

SUBSYSTEM=="usb", ATTR{idVendor}=="19d2", MODE="0666", GROUP="plugdev"

If the file doesn't exist, create it. The rules.d directory is usually read only by default, so you may have to use chmod to make the directory writeable, or the file, or both.

Once you've saved the file, and closed it,  make the file readable:

$ sudo chmod a+r /etc/udev/rules.d/android.rules

Now that the udev rules have been updated, restart the udev daemon. For ubuntu:

sudo service udev restart

Finally, unplug and the USB cable but don't replug it in because we need to enable remote debugging on the phone first.

Enable remote debugging

Before you plug your phone back into your USB port, put it USB developer mode. This allows you to debug and flash the phone. To enable developer mode, on your phone select Settings app -> Device information -> More Information -> Developer -> Remote debugging (this was called Developer mode on older versions.) 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 before, this will trigger udev to detect the phone and create the device node with the right permissions). Now you can check if you can list your device via the adb devices command. If everything has worked ok, you should see an output similar to this (the following is for a Geeksphone Keon):

$ adb devices
List of devices attached
full_keon       device

If the device did not list as expect, check the file name and the script are all correct (see previous section), then restart the computer and retype the command again. Note also that if your device uses fastboot, the bootloader may identify itself with a different vendor ID than the one you see when the device boots normally.

Backup the phone system partition

Note: You have to do this before you build your device if you do not have existing system backup. Because some libraries will be referenced in build time. These library might be proprietary so we can't provide in our code base.

It is recommended to back up the entire Android system partition on your phone.

You can use this copy of the binary blobs for Android in case you later delete your B2G tree. To do this, run:

adb pull /system <backup target dir>/system

 Depending on the phone, you may also need to pull the /data and/or /vendor directories:

adb pull /data <backup target dir>/data
adb pull /vendor <backup target dir>/vendor

If the pull commands fail with "insufficient permission" message, try the following:

  • stop and restart the adb server, or if that fails,
  • double-check that you have granted root permissions to the 'adb' tool within your custom ROM (e.g. under CyanogenMod, change 'Settings -> System -> Developer Options -> Root Access' to 'Apps and ADB' or 'ADB only').
  • Verify that you have set up the udev rule correctly (see {{ anch("For Linux: configure the udev rule for your phone") }}.

On to the next step

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

Revision Source

<p>Before obtaining the code to build Firefox OS, you need a properly configured <a href="https://developer.mozilla.org/en-US/docs/Developer_Guide/Build_Instructions" title="https://developer.mozilla.org/en-US/docs/Developer_Guide/Build_Instructions">build system</a>. You can currently build on 64-bit Linux distributions and OS X.</p>
<div class="note">
 <p>Note: To build Firefox OS onto a phone, begin with your phone NOT connected to your computer. We'll tell you when to plug it in.</p>
</div>
<h2 id="Have_a_compatible_device.2Femulator">Have a compatible device/emulator</h2>
<p><span id="answer_long0" style="display: block;">You need to have a compatible device to build onto, or to use an emulator. Though we support several phones, some have multiple variations. We currently support specific variations and some devices have better support than others: </span></p>
<h3 id="Tier_1">Tier 1</h3>
<p>Tier 1 devices represent a primary target for development and will typically be the first to receive bug fixes and feature updates.</p>
<dl>
 <dt>
  Keon</dt>
 <dd>
  Keon is the <a href="http://www.geeksphone.com/" title="http://www.geeksphone.com/">Geeksphone</a> Keon device, which is one of the initial developer phones. Note that builds for this device are provided by Geeksphone.</dd>
 <dt>
  Inari</dt>
 <dd>
  Inari is another testing device. Use this configuration to build for the ZTE Open device.</dd>
 <dt>
  Unagi</dt>
 <dd>
  Unagi is a phone being used as a test and development platform as a low-to-midrange smartphone. Many core Firefox OS developers are working on Unagi.</dd>
 <dt>
  Otoro</dt>
 <dd>
  Otoro is a phone being used as a test and development platform as a low-to-midrange smartphone. Many core Firefox OS developers are working on Otoro.</dd>
 <dt>
  <a href="/en-US/docs/Mozilla/Firefox_OS/Pandaboard" title="/en-US/docs/Mozilla/Firefox_OS/Pandaboard">Pandaboard</a></dt>
 <dd>
  The Pandaboard is a development board based on the OMAP 4 architecture, used to do development work on mobile platforms.</dd>
 <dt>
  <a href="/en-US/docs/Mozilla/Firefox_OS/Using_the_B2G_emulators" title="en-US/docs/Mozilla/Firefox_OS/Using_the_B2G_emulators">Emulator (ARM and x86)</a></dt>
 <dd>
  There are two emulators available: one emulates ARM code and the other runs everything in x86 code. <a href="/en-US/docs/Mozilla/Firefox_OS/Using_the_B2G_emulators" title="/en-US/docs/Mozilla/Firefox_OS/Using_the_B2G_emulators">Learn more about installing and using the emulators</a>.</dd>
 <dd>
  <strong>Note that you shouldn't use the x86 emulator — it is hard to install and not well supported.</strong></dd>
 <dt>
  <a href="/en-US/docs/Mozilla/Firefox_OS/Using_the_B2G_desktop_client" title="/en-US/docs/Mozilla/Firefox_OS/Using_the_B2G_desktop_client">Desktop</a></dt>
 <dd>
  You can also build a desktop version of Firefox OS; this runs <a href="/en-US/docs/Mozilla/Gecko" title="/en-US/docs/Mozilla/Gecko">Gecko</a> in a <a href="/en-US/docs/XULRunner" title="/en-US/docs/XULRunner">XULRunner</a> application, and you then use the <a href="/en-US/docs/Mozilla/Firefox_OS/Platform/Gaia/Introduction_to_Gaia" title="/en-US/docs/Mozilla/Firefox_OS/Platform/Gaia/Introduction_to_Gaia">Gaia</a> user experience inside it.</dd>
</dl>
<p>You can, of course, build the <a href="/en-US/docs/Mozilla/Firefox_OS/Using_the_B2G_desktop_client" title="en-US/docs/Mozilla/Firefox_OS/Using_the_B2G_desktop_client">desktop client</a> or one of the <a href="/en-US/docs/Mozilla/Firefox_OS/Using_the_B2G_emulators" title="en-US/docs/Mozilla/Firefox_OS/Using_the_B2G_emulators">emulators</a> without a phone.</p>
<h3 id="Tier_2">Tier 2</h3>
<p><span id="answer_long1" style="display: block;">Tier 2 devices are generally functional and many developers (especially app developers) are using them, so they tend to pick up changes secondarily.</span></p>
<dl>
 <dt>
  <a href="/en-US/docs/Mozilla/Firefox_OS/Samsung_Nexus_S" title="/en-US/docs/Mozilla/Firefox_OS/Samsung_Nexus_S"><span class="link-https">Samsung Nexus S</span></a></dt>
 <dd>
  The known working model numbers of Nexus S devices are GT-I9020A and GT-I9023. Others may work.</dd>
 <dt>
  Samsung Nexus S 4G</dt>
 <dd>
  The SPH-D720 is supported as a tier 2 device.</dd>
</dl>
<h3 id="Tier_3">Tier 3</h3>
<p><span id="answer_long1" style="display: block;">Firefox OS can be built for these devices, but they are not being actively worked on a regular basis by core developers. Their reliability and feature set may lag noticeably behind tier 1 and even tier 2 devices.</span></p>
<dl>
 <dt>
  Samsung Galaxy S2</dt>
 <dd>
  The only model that works is the i9100; no other variants are officially compatible. (i9100P might work, since the only change is a NFC chip added)</dd>
 <dt>
  Samsung Galaxy Nexus</dt>
 <dd>
  We are not currently aware of any variations that are not compatible.</dd>
 <dt>
  Tara</dt>
 <dd>
  Tara is another testing device. Manifest of Tara is in master branch only. The script of getting Tara code is "BRANCH=master ./config.sh tara".</dd>
</dl>
<div class="warning">
 <strong>Important</strong>: Only devices running at least <strong>Android 4</strong> (aka <strong>Ice Cream Sandwich</strong>) are supported. If your device is listed above but running an older version of Android, please update it before doing anything.</div>
<div class="note">
 <p>Note: Tier 2 and Tier 3 devices have a software home button instead of a hardware home button</p>
 <p>All Tier 1 devices have a hardware Home button which returns the user to the home screen. Most current ICS based Android devices use onscreen touch buttons for navigation. We have a virtual home button for the devices without hardware home button now. If it's not automatically enabled,&nbsp;<span style="line-height: 1.5em; font-size: 14px;">open the Settings app and navigate down through Device Information -&gt; More Information -&gt; Developer, then toggle on the "Enable software home button" preference.</span></p>
</div>
<h2 id="Requirements_for_Linux">Requirements for Linux</h2>
<p>To build on Linux, you'll need:</p>
<ul>
 <li>A <strong>64 bit GNU/Linux</strong> distribution (Ubuntu 12.04 recommended).</li>
 <li>At least <strong>4 GB</strong> of RAM/swap space.</li>
 <li>At least <strong>20 GB</strong> of available hard disk space.</li>
</ul>
<p>This is more than the bare minimum, but sometimes building fails just because it's missing resources.</p>
<p>You will also need the following tools installed:</p>
<ul>
 <li><strong>autoconf 2.13</strong></li>
 <li><strong>bison</strong></li>
 <li><strong>bzip2</strong></li>
 <li><strong>ccache</strong></li>
 <li><strong>curl</strong></li>
 <li><strong>flex</strong></li>
 <li><strong>gawk</strong></li>
 <li><strong>git</strong></li>
 <li><strong>gcc / g++ / g++-multilib</strong></li>
 <li><strong>make</strong></li>
 <li><strong>OpenGL shared libraries</strong></li>
 <li><strong>patch</strong></li>
 <li><strong>X11 headers</strong></li>
 <li><strong>32-bit ncurses</strong></li>
 <li><strong>32-bit zlib</strong></li>
</ul>
<h3 id="Emulator_build_issues"><strong>Emulator build issues</strong></h3>
<p>If you are making an <strong>emulator</strong> build, you need to pay attention to these issues:</p>
<p>First, <strong>note that you shouldn't use the x86 emulator — it is hard to install and not well supported.</strong></p>
<p>Next, the build-system for the emulator builds both 32bit and 64bit versions of the emulator. As the emulator depends on OpenGL, this means that you need to have both 32bit and 64bit versions of OpenGL libraries installed on your system. See the discussion in bug <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=897727" title="https://bugzilla.mozilla.org/show_bug.cgi?id=897727">bug 897727</a>.</p>
<p>There are two ways that you can solve this problem:</p>
<h4 id="Solution_.231.3A_have_both_32bit_and_64bit_OpenGL_libs_installed.2C_with_the_right_symlinks">Solution #1: have both 32bit and 64bit OpenGL libs installed, with the right symlinks</h4>
<p>If your linux distro has multilib packages for OpenGL libraries, you can attempt installing them. You might then have to manually create some symlinks.</p>
<p>For example, here is the situation on Ubuntu 12.04 LTS x86-64. On this distribution, the libgl1-mesa-dev package cannot be installed simultaneously in x86-64 and i386 versions, but you can have the following combination of packages simultaneously installed:</p>
<pre class="bz_comment_text" id="comment_text_12">
sudo apt-get install libgl1-mesa-dev libglapi-mesa:i386 libgl1-mesa-glx:i386</pre>
<p>After having run this command, you will still have to manually create some symlinks for the emulator build to succeed:</p>
<pre class="note">
$ sudo ln -s /usr/lib/i386-linux-gnu/libX11.so.6 /usr/lib/i386-linux-gnu/libX11.so
$ sudo ln -s /usr/lib/i386-linux-gnu/mesa/libGL.so.1 /usr/lib/i386-linux-gnu/libGL.so</pre>
<h4 id="Solution_.232.3A_just_patch_the_emulator_so_it_only_builds_64bit">Solution #2: just patch the emulator so it only builds 64bit</h4>
<p>Just apply <a href="https://bug897727.bugzilla.mozilla.org/attachment.cgi?id=786280" title="https://bug897727.bugzilla.mozilla.org/attachment.cgi?id=786280">this patch</a> to the sdk/ git repository under the B2G repo. This will cause the B2G emulator to only attempt to build the 64bit emulator if you're on a 64bit system, thus avoiding any multilib issues. The 32bit emulator is unused anyway on a 64bit system. This is the simplest solution... until this patch eventually bit-rots.</p>
<h3 id="64_bit_requirement_installation">64 bit requirement installation</h3>
<p>This section lists the commands you need to run in different Linux distributions to install at the requirements for building Firefox OS.</p>
<h4 id="Ubuntu_12.04_.2F_Linux_Mint_13_.2F_Debian_6">Ubuntu 12.04 / Linux Mint 13 / Debian 6</h4>
<p>Run the following command in Terminal:</p>
<pre>
$ 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</pre>
<p>And see the above comments about emulator build issues!</p>
<h4 id="Ubuntu_12.10">Ubuntu 12.10</h4>
<p>Run the following command in Terminal:</p>
<pre>
$ sudo apt-get install autoconf2.13 bison bzip2 ccache curl flex gawk gcc g++ g++-multilib gcc-4.6 g++-4.6 g++-4.6-multilib git ia32-libs lib32ncurses5-dev lib32z1-dev libgl1-mesa-dev libx11-dev make zip</pre>
<p>In addition to the emulator build issues discussed above, the compiler will default to gcc-4.7, which will fail to build with an error along the following lines:</p>
<p>"<code>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"</code></p>
<p>To fix this, you will need to specify GCC 4.6 as the default host compiler after having retrieved the B2G sources: Read <a href="/en-US/docs/Mozilla/Firefox_OS/Customization_with_the_.userconfig_file#Changing_the_default_host_compiler">Changing the default host compiler</a> to find out how to do it.</p>
<p class="note">In a fresh Ubuntu 12.10 install, you'll get an error about unmet dependencies for ia32-libs. The following commands fix it:</p>
<pre>
sudo dpkg --add-architecture i386
sudo apt-get update
sudo apt-get install ia32-libs</pre>
<h4 id="Ubuntu_13.04">Ubuntu 13.04</h4>
<p>Run the following command in Terminal:</p>
<pre>
$ sudo apt-get install --no-install-recommends autoconf2.13 bison bzip2 ccache curl flex gawk gcc g++ g++-multilib gcc-4.6 g++-4.6 g++-4.6-multilib git ia32-libs lib32ncurses5-dev lib32z1-dev zlib1g:amd64 zlib1g-dev:amd64 zlib1g:i386 zlib1g-dev:i386 libgl1-mesa-dev libx11-dev make zip</pre>
<p>In addition to the emulator build issues discussed above, the compiler will default to gcc-4.7, which will fail to build with an error along the following lines:</p>
<p>"<code>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"</code></p>
<p>To fix this, you will need to specify GCC 4.6 as the default host compiler after having retrieved the B2G sources: Read <a href="/en-US/docs/Mozilla/Firefox_OS/Customization_with_the_.userconfig_file#Changing_the_default_host_compiler">Changing the default host compiler</a> to find out how to do it.</p>
<h4 id="Ubuntu_13.10">Ubuntu 13.10</h4>
<p>With Ubuntu 13.10, multi-arch packages are now the main way to support multiple architectures (e.g. 32-bit on a 64-bit install).&nbsp; You must tell your Ubuntu system that you want to support 32-bit packages as well:</p>
<pre>
sudo dpkg --add-architecture i386
sudo apt-get update
</pre>
<p>Once you've completed that, then you can install the necessary packages:</p>
<pre>
sudo apt-get install --no-install-recommends autoconf2.13 bison bzip2 ccache curl flex gawk gcc g++ g++-multilib gcc-4.6 g++-4.6 g++-4.6-multilib git lib32ncurses5-dev lib32z1-dev zlib1g:amd64 zlib1g-dev:amd64 zlib1g:i386 zlib1g-dev:i386 libgl1-mesa-dev libx11-dev make zip</pre>
<h4 id="Fedora_17.2F18.2F19">Fedora 17/18/19</h4>
<p>Run the following command in Terminal:</p>
<pre class="note">
$ 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</pre>
<p>In addition to the above you will need GCC 4.6.x in order to compile the project:</p>
<ul>
 <li><a href="http://people.mozilla.org/~gsvelto/gcc-4.6.4-fc18.tar.xz">Pre-compiled GCC 4.6.x for&nbsp; Fedora 17/18</a></li>
 <li><a href="http://people.mozilla.org/~gsvelto/gcc-4.6.4-fc19.tar.xz">Pre-compiled GCC 4.6.x for Fedora 19</a></li>
</ul>
<p>Download the right version for your Fedora installation, then install it to <code>/opt,</code> with the following command on Fedora 17/18:</p>
<pre class="note">
$ curl -O http://people.mozilla.org/~gsvelto/gcc-4.6.4-fc18.tar.xz
$ sudo tar -x -a -C /opt -f gcc-4.6.4-fc18.tar.xz
</pre>
<p>And with the following command for Fedora 19:</p>
<pre class="note">
$ curl -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
</pre>
<p>You will need to specify GCC 4.6.x as the default host compiler after having retrieved the B2G sources: Read <a href="/en-US/docs/Mozilla/Firefox_OS/Customization_with_the_.userconfig_file#Changing_the_default_host_compiler">Changing the default host compiler</a> to find out how to do it.</p>
<p>If build fails with the compiler complaining about not finding libmpc.so.2, install the package compat-libmpc</p>
<h4 id="Arch_Linux"><strong>Arch Linux</strong></h4>
<p>Run the following command in Terminal:</p>
<pre class="note">
$ sudo <span style=""><span style="">pacman -S --needed </span></span><span style=""><span style="">alsa-lib </span></span><span style=""><span style="">autoconf2.13</span></span><span style=""><span style=""> bison</span></span><span style=""><span style=""> ccache</span></span><span style=""><span style=""> </span></span><span style=""><span style="">curl firefox </span></span><span style=""><span style="">flex </span></span><span style=""><span style="">gcc-multilib </span></span><span style=""><span style="">git </span></span><span style=""><span style="">gperf </span></span><span style=""><span style="">libnotify </span></span><span style=""><span style="">libxt </span></span><span style=""><span style="">libx11 mesa multilib-devel </span></span><span style=""><span style="">wget wireless_tools </span></span><span style=""><span style="">yasm</span></span><span style=""><span style=""> zip </span></span><span style=""><span style="">lib32-mesa </span></span>lib32-mesa-libgl <span style=""><span style="">lib32-ncurses lib32-readline</span></span><span style=""><span style=""> </span></span><span style=""><span style="">lib32-zlib</span></span></pre>
<p>To install the lib32-* packages you need to have the multilib repository enabled.</p>
<p>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 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:</p>
<pre>
<span style=""><span style="">$ sudo pacman -S python-virtualenvwrapper
$ </span></span>source /usr/bin/virtualenvwrapper.sh
$ mkvirtualenv -p `which python2` firefoxos
$ workon firefoxos
</pre>
<h2 id="Requirements_for_Mac_OS_X">Requirements for Mac OS X</h2>
<p>To build Firefox OS on Mac OS X, there are a number of prequisite steps you need to follow, which are detailed below. We also discuss common errors you might come across in particular situations, and solutions to those.</p>
<div class="note">
 <p><strong>Note: Configuring and Building B2G for Keon WON'T WORK on a Mac</strong>. You'll need to use Linux to build B2G for this device.</p>
</div>
<h3 id="Install_XCode_Command_Line_Utilities"><strong>Install XCode Command Line Utilities</strong></h3>
<p>You need to install Xcode's Command Line Utilities. You can download <em>just</em> the Command Line Utilities from <a href="https://developer.apple.com/downloads/" title="https://developer.apple.com/downloads/">Apple's developer downloads page</a> for your particular version of OS X, however if you would like the entire Xcode suite of applications, you can&nbsp;<a class="external" href="http://itunes.apple.com/us/app/xcode/id497799835?mt=12" style="line-height: 1.572;" title="http://itunes.apple.com/us/app/xcode/id497799835?mt=12">install Xcode</a><span style="line-height: 1.572;">&nbsp;through the Mac App Store.&nbsp;</span></p>
<p>Xcode 4.3.1 (OS X 10.7 "Lion") and other newer versions such as 4.4.1+ (that is, Mac OS X10.8 "Mountain Lion"), won't necessarily include the required Command Line Utilities. When you install Xcode, make sure to go into Preferences, then the Downloads panel, and install the Command Line Utilities. In addition, make sure you have at least 20 GB of free disk space.</p>
<p><img alt="Screenshot of Xcode Downloads Command Line Tools" src="/files/4557/xcode_downloads_command_line_tools.png" style="width: 750px; height: 528px;" /></p>
<div class="note">
 <strong>Note:</strong> The Firefox OS emulator requires a Core 2 Duo processor or later; that is, a system that is compatible with Mac OS X 10.7 "Lion." You do not actually have to be running Lion, you just have to be compatible with it. You can, however, build any Firefox OS build on many older Macs.</div>
<h3 id="Run_Firefox_OS_Mac_Bootstrap">Run Firefox OS Mac Bootstrap</h3>
<p>Next, open a terminal and run the following command:</p>
<pre class="brush: bash">
curl -fsSL https://raw.github.com/mozilla-b2g/B2G/master/scripts/bootstrap-mac.sh | bash</pre>
<p>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. The script will check for and install the following items:</p>
<ul>
 <li><code>git</code></li>
 <li><code>gpg</code></li>
 <li><code>ccache</code></li>
 <li><code>yasm</code></li>
 <li><code>autoconf-213</code></li>
 <li><code>gcc-4.6</code></li>
 <li><code>homebrew</code></li>
</ul>
<h4 id="Xcode_wrangling">Xcode wrangling</h4>
<p>If you have already upgraded to Xcode 4.4+ and get the message that Xcode is outdated, check the Xcode path with:</p>
<pre>
xcode-select -print-path</pre>
<p>If it still points to <code>/Developer</code> you can update the path with:</p>
<pre>
sudo xcode-select -switch /Applications/Xcode.app</pre>
<h4 id="Making_the_Mac_OS_X_10.6_SDK_available">Making the Mac OS X 10.6 SDK available</h4>
<p>You also need to have the Mac OS X 10.6 SDK available. The SDK needs to be available at</p>
<pre>
/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/</pre>
<p>If it cannot be found there you will need to extract and copy it from Xcode 4.3. To do this:</p>
<ol>
 <li>Download the XCode 4.3 .dmg file from the <a class="external" href="https://developer.apple.com/downloads/index.action">Apple Developer</a> portal (you'll need an <a href="https://developer.apple.com/register/index.action" title="https://developer.apple.com/register/index.action">Apple Developer account</a>).</li>
 <li>Download the utility <a href="http://www.charlessoft.com/" title="http://www.charlessoft.com/">Pacifist</a> and use it to extract the 10.6 SDK from the XCode 4.3 .dmg file. Click on the "Extract Package" button, find the SDK by searching for 10.6 in the search box, then <em>Ctrl + click</em> on the MacOSX10.6.sdk directory and Extract it to a suitable location.</li>
 <li>Add a symlink from the 10.6 SDK location to the <code>/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/</code> directory. For example, if you put the 10.6 SDK on your desktop, the comment would be</li>
</ol>
<pre>
ln -s /Users/<em>&lt;yourusername&gt;</em>/Desktop/MacOSX10.6.sdk /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/</pre>
<div class="note">
 <p><strong>Note</strong>: We can drop the 10.6 SDK requirement after <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=784227" title="https://bugzilla.mozilla.org/show_bug.cgi?id=784227">bug 784227</a> has been fixed, and our version of <a href="https://github.com/mozilla-b2g/B2G/issues/189" title="https://github.com/mozilla-b2g/B2G/issues/189">platform_build has been updated</a>.</p>
</div>
<h3 id="Be_aware_of_Mac_file_system_case_sensitivity">Be aware of Mac file system case sensitivity</h3>
<p>By default, Mac OS X ships with a case-insensitive file system.&nbsp; This is problematic because the Linux kernel has a number of files with the same name, but different case.&nbsp; For example, see the header files <code>xt_CONNMARK.h</code> and <code>xt_connmark.h</code>.&nbsp; This results in a number of files appearing to be modified in <code>/kernel</code> after a fresh <code>./config.sh</code>.</p>
<p>In many cases you can run the build just fine; for some platforms, however, you may encounter the following error:</p>
<pre>
<span class="quote">ERROR: You have uncommited changes in kernel
You may force overwriting these changes
with |source build/envsetup.sh force|

ERROR: Patching of kernel/ failed.</span></pre>
<p><span class="quote">Please see <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=867259" title="https://bugzilla.mozilla.org/show_bug.cgi?id=867259">bug 867259</a></span> for more discussion and possible fixes for this problem.</p>
<p>Alternatively, it will always be safest to build on a case sensitive file system.&nbsp; The easiest way to do this is to create a separate, mountable disk image with case-sensitivity enabled.&nbsp; You can do this using Apple's Disk Utility application or from the command line:</p>
<pre>
hdiutil create -volname 'firefoxos' -type SPARSE -fs 'Case-sensitive Journaled HFS+' -size 40g ~/firefoxos.sparseimage</pre>
<p>Mount the drive with:</p>
<pre>
open ~/firefoxos.sparseimage</pre>
<p>Change into the mounted drive with:</p>
<pre>
cd /Volumes/firefoxos/</pre>
<p>You can then check out the code and compile from this location without worrying about case-sensitivity problems.</p>
<h3 id="Mountain_Lion_homebrew_gotcha">Mountain Lion homebrew gotcha</h3>
<div>
 <div>
  If you are on Mountain Lion and you receive an error during the installation of the dependencies via homebrew, such as:</div>
</div>
<div>
 <pre>
clang: error: unable to execute command: Segmentation fault: 11</pre>
 ... try reinstalling the dependency manually adding the --use-gcc flag, for example:
 <pre>
brew install mpfr --use-gcc</pre>
</div>
<h3 id="Follow_Samsung_Galaxy_S2_extra_steps">Follow Samsung Galaxy S2 extra steps</h3>
<p>If you plan to build for the Samsung Galaxy S2, you will also need to install heimdall. See {{ anch("Installing heimdall") }} for details. This is <strong>not</strong> done for you by the bootstrap script!</p>
<div class="note">
 <strong>Note:</strong> If you have installed the <a class="external" href="http://www.samsung.com/us/kies/" title="http://www.samsung.com/us/kies/">Samsung Kies</a> tool, which is used to manage the contents of many Samsung phones, you will have to remove it before you can flash Firefox OS onto your device. You can use the standard application removal process on Windows; on Mac, the Kies install disk image has a utility to fully remove Kies from your system. Flashing <strong>will not work</strong> if you have Kies installed. If you forget to remove Kies, the build system will detect it and remind you to uninstall it. Note also that the uninstall tool does not correctly remove the folder <code>~/Library/Application Support/.FUS</code>, and leaves a reference to a utility there in your user startup items list. You will want to remove these manually.</div>
<h3 class="note" id="Fix_libmpc_dependency_if_broken">Fix libmpc dependency if broken</h3>
<p>gcc 4.6 was built with libmpc 0.9; if you then use homebrew to update packages, libmpc gets updated to version 1.0, but homebrew doesn't rebuild gcc 4.6 after the library version changes. So you need to create a symlink to make things work again, like this:</p>
<pre>
cd /usr/local/lib/
ln -s libmpc.3.dylib libmpc.2.dylib</pre>
<h3 id="Optional.3A_Install_HAX">Optional: Install HAX</h3>
<p>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 <a class="external" href="http://software.intel.com/en-us/articles/intel-hardware-accelerated-execution-manager/" title="http://software.intel.com/en-us/articles/intel-hardware-accelerated-execution-manager/">download and install</a> it. It's not required, but it can improve emulation performance and stability.&nbsp;&nbsp;</p>
<p>Before you install HAX you will need to install the <a href="http://developer.android.com/sdk/index.html" title="http://developer.android.com/sdk/index.html">Android SDK</a>.</p>
<h2 class="note" id="Install_adb">Install adb</h2>
<p>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).&nbsp; For this, you will need <code>adb</code>, the Android Debug Bridge.</p>
<p>You can download and install <code>adb</code> as part of the Android SDK package, for Mac, Linux or Windows - visit the <a href="http://developer.android.com/sdk/index.html">Get the Android SDK</a> page.</p>
<p>Newer Linux distributions have <code>adb</code> already in their repositories. For Ubuntu 12.10 and later, run the following command:</p>
<pre>
sudo apt-get install android-tools-adb</pre>
<p>Or for Fedora 18/19:</p>
<pre>
sudo yum install android-tools</pre>
<p>If your distribution does not have packages for <code>adb </code>available (i.e. Ubuntu 12.04 or Fedora 17), you'll need to install the <a class="external" href="http://developer.android.com/sdk/index.html" title="http://developer.android.com/sdk/index.html">Android SDK starter package</a> for your platform (you'll want the&nbsp;<em>ADT Bundle</em>, not the <em>SDK Tools Only</em> option). Then run their package manager, <code>$SDK_HOME/tools/android</code>, and use the GUI to install "Android SDK Platform-tools".</p>
<p>Find out where <code>adb</code> is installed (usually in <code>usr/bin</code>, possibly additionally inside <code>adt/platform-tools</code>, depending on how you installed it). Be sure to add this directory to your <code>PATH</code>. This can be done by adding the line</p>
<pre>
PATH=$SDK_HOME:$PATH</pre>
<p>replacing&nbsp;<code>$SDK_HOME</code> with the location of the android sdk,&nbsp;to your <code>~/.bashrc</code> or equivalent.</p>
<h2 class="note" id="Install_heimdall">Install heimdall</h2>
<p>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 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 <strong>not</strong> needed for any other device. For other devices, we build and use the fastboot utility instead.</p>
<div class="note">
 <strong>Note:</strong> Again, it's important to note that this is <strong>only required for installing Firefox OS on the Samsung Galaxy S2</strong>.</div>
<p>There are two ways to install heimdall:</p>
<ul>
 <li>You can <a class="link-https" href="https://github.com/Benjamin-Dobell/Heimdall" title="https://github.com/Benjamin-Dobell/Heimdall">download the code</a> GitHub and build it yourself.</li>
 <li>Use a package manager to install it.
  <ul>
   <li>On Linux: <code>sudo apt-get install libusb-1.0-0 libusb-1.0-0-dev</code></li>
   <li>On Mac, you can <a class="link-https" href="https://github.com/downloads/Benjamin-Dobell/Heimdall/heimdall-suite-1.3.2-mac.dmg" title="https://github.com/downloads/Benjamin-Dobell/Heimdall/heimdall-suite-1.3.2-mac.dmg">download an installer package</a> and use that.</li>
  </ul>
 </li>
</ul>
<h2 id="Configure_ccache">Configure ccache</h2>
<p>The B2G build process uses ccache. The default cache size for ccache is 1GB, but the B2G build easily saturates this; around 3GB is recommended. You can configure your cache by running the following command inside terminal:</p>
<pre>
<code>$ ccache --max-size 3GB</code></pre>
<h2 id="For_Linux.3A_configure_the_udev_rule_for_your_phone">For Linux: configure the udev rule for your phone</h2>
<div class="note">
 <p>Note: This section is specific to Linux; Mac OSX has the necessary device permissions set up already.</p>
</div>
<p>Next, you need to confingure the udev rule for your phone,</p>
<p>You can get the USB vendor ID by running <code>lsusb</code> with your phone plugged in, but typically it's Google <code>18d1,</code>&nbsp;Samsung <code>04e8</code>, ZTE <code>19d2</code>, Geeksphone/Qualcomm <code>05c6</code>. Add this line in your <code>/etc/udev/rules.d/android.rules</code> file (replacing <code>XXXX</code> with the ID for your device):</p>
<pre>
SUBSYSTEM=="usb", ATTR{idVendor}=="XXXX", MODE="0666", GROUP="plugdev"</pre>
<p>Take ZTE for example, the content in android.rules will be</p>
<pre style="font-size: 14px;">
SUBSYSTEM=="usb", ATTR{idVendor}=="19d2", MODE="0666", GROUP="plugdev"</pre>
<div class="note">
 <p><span style="line-height: 1.572;">If the file doesn't exist, create it. The <code>rules.d</code> directory is usually read only by default, so you may have to use <code>chmod</code> to make the directory writeable, or the file, or both.</span></p>
</div>
<p><span style="line-height: 1.572;">Once you've saved the file, and closed it,&nbsp; make the file readable:</span></p>
<pre>
$ sudo chmod a+r /etc/udev/rules.d/android.rules
</pre>
<p>Now that the udev rules have been updated, restart the udev daemon. For ubuntu:</p>
<pre>
sudo service udev restart</pre>
<p>Finally, unplug and the USB cable but don't replug it in because we need to enable remote debugging on the phone first.</p>
<h2 id="Enable_remote_debugging">Enable remote debugging</h2>
<p>Before you plug your phone back into your USB port, put it USB developer mode. This allows you to debug and flash the phone. To enable developer mode, on your phone select <code>Settings app</code> -&gt; <code>Device information</code> -&gt; <code>More Information</code> -&gt; <code>Developer</code> -&gt; <code>Remote debugging</code> (this was called Developer mode on older versions.) Once the option is checked, remote debugging is enabled, and you are ready to go.</p>
<p>At this point, connect your phone to your computer via a USB cable (if you created the udev rule before, this will trigger udev to detect the phone and create the device node with the right permissions). Now you can check if you can list your device via the <code>adb devices</code> command. If everything has worked ok, you should see an output similar to this (the following is for a Geeksphone Keon):</p>
<pre style="font-size: 14px;">
$ adb devices
List of devices attached
full_keon       device</pre>
<p>If the device did not list as expect, check the file name and the script are all correct (see previous section), then restart the computer and retype the command again. Note also that if your device uses fastboot, the bootloader may identify itself with a different vendor ID than the one you see when the device boots normally.</p>
<h2 id="Backup_the_phone_system_partition">Backup the phone system partition</h2>
<div class="warning">
 <p><strong>Note:</strong> You have to do this before you build your device if you do not have existing system backup. Because some libraries will be referenced in build time. These library might be proprietary so we can't provide in our code base.</p>
</div>
<p>It is recommended to back up the entire Android system partition on your phone.</p>
<p>You can use this copy of the binary blobs for Android in case you later delete your B2G tree. To do this, run:</p>
<pre>
adb pull /system &lt;backup target dir&gt;/system
</pre>
<p>&nbsp;Depending on the phone, you may also need to pull the /data and/or /vendor directories:</p>
<pre>
adb pull /data &lt;backup target dir&gt;/data
adb pull /vendor &lt;backup target dir&gt;/vendor
</pre>
<p>If the pull commands fail with "insufficient permission" message, try the following:</p>
<ul>
 <li>stop and restart the adb server, or if that fails,</li>
 <li>double-check that you have granted <em>root</em> permissions to the 'adb' tool within your custom ROM (e.g. under CyanogenMod, change 'Settings -&gt; System -&gt; Developer Options -&gt; Root Access' to 'Apps and ADB' or 'ADB only').</li>
 <li>Verify that you have set up the udev rule correctly (see {{ anch("For Linux: configure the udev rule for your phone") }}.</li>
</ul>
<h2 id="On_to_the_next_step">On to the next step</h2>
<p>At this point, you should be ready to <a href="/en-US/docs/Mozilla/Firefox_OS/Preparing_for_your_first_B2G_build" title="en-US/docs/Mozilla/Firefox_OS/Preparing_for_your_first_B2G_build">fetch the Firefox OS code</a>!</p>
Revert to this revision