Firefox OS build prerequisites

  • Revision slug: Mozilla/Boot_to_Gecko/B2G_build_prerequisites
  • Revision title: B2G build prerequisites
  • Revision id: 300941
  • Created:
  • Creator: Sheppy
  • Is current revision? No
  • Comment

Revision Content

Before you can even get the code, so you can build Boot to Gecko. You'll need a properly-configured build system. You can currently build on 64-bit Linux distributions and Mac OS X.

Have a compatible phone or use emulators

This is important. Even though we support several phones, some of them are available in multiple variations, and only select variations of them may be supported. In addition, some devices are supported better than others. At this time, the following devices have Firefox OS ports available:

Tier 1

Tier 1 devices are those which are being actively supported as a primary target for development. Features will typically arrive, and bugs will be fixed, first for these devices.

Otoro
Otoro is a phone being used as a test and development platform as a low-to-midrange smartphone. Most 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.
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

The 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

These devices are those for which Firefox OS can be built but are not being actively worked on on a regular basis by core developers, so their reliability and feature set may lag noticeably behind the 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
I'm not currently aware of any variations that are not compatible.
Important: Only devices running 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.

Requirements for Linux

To build on Linux, you'll need to have a system configured with:

  • An installed Linux distribution (we recommend Ubuntu 11.10, and a 64-distribution is preferable).
  • At least 4 GB of swap space.
  • At least 25 GB of available hard disk space.

This is more than the bare minimum, but you'll find after a while that you'll need the resources.

It's possible to use other distributions, but we recommend this one just to ensure everything works as expected.

You will also need the following tools installed:

  • autoconf-2.13
  • git
  • ccache
  • gcc/g++, and you will need g++ multilibs
  • bison
  • flex
  • 32-bit ncurses (libncurses5-dev on Ubuntu/Debian and lib32ncurses5-dev on Ubuntu/Debian x64)
  • 32-bit zlib (ia32-libs and lib32z1-dev on Ubuntu/Debian)
  • foo
  • make
  • curl
  • bzip2
  • heimdall (if building for the Samsung Galaxy S2; see {{ anch("Installing heimdall") }})
Note: When building on 64-bit Ubuntu, you may find that you need to add symlinks for the 32-bit versions of libX11.so and libGL.so; to do so, go into /usr/lib/i386-linux-gnu and create symlinks from libX11.so to libX11.so.6 and from libGL.so to mesa/libGL.so.

Requirements for Mac OS X

To build Firefox OS on Mac OS X, you need to install Xcode, which is available through the Mac App Store.  On Xcode version 4.4.1+ (that is, Mac OS X10.8 "Mountain Lion"), open Xcode, under the Downloads tab, under the Components button, click Install on the Command Line Tools.  On Xcode pre-version 4.4.1 (OS X 10.7 "Lion"), be 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.

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.

Then you need to open a terminal and run this command in the terminal; this will pull and run a bootstrap script that makes sure you have all prerequisites met.

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

This will check to see if you have all the things you need to be able to build the emulator, and will prompt you for permission to install anything you're missing. The items this script will check for and install for you are:

  • git
  • gpg
  • ccache
  • yasm
  • autoconf-213
  • gcc-4.6
  • homebrew
Note: 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
Next to that be sure that you have the Mac OS X 10.6 SDK 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 the Xcode 4.3 DMG file which is available at the Apple Developer portal. You can use the utility Pacifist to extract the 10.6 SDK. Be sure to add a symlink to it to the /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/ directory.

If you are building on OS X 10.8 "Mountain Lion" (Xcode 4.4.1 or later) and encounter the following error:

external/qemu/android/skin/trackball.c:130:25: error: 'M_PI' undeclared (first use in this function)
Edit the file: B2G/external/qemu/makefile.android and add in line 78:

MY_CFLAGS += -DM_PI=3.14159265358979323846264338327950288   #/* B2G_fix: not finding M_PI constant */

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.
Note: Mac OS X uses a case insensitive filesystem by default, which will prevent you from building Firefox OS down the road (EDITOR'S NOTE: I have never had a problem with this).  You should create a case sensitive sparse disk image work from within that directory.  To buld the case sensitive disk image:
hdiutil create -type SPARSE -fs 'Case-sensitive Journaled HFS+' -size 40g ~/firefoxos.dmg

Mount the drive with:

open ~/firefoxos.dmg

Change into the mouted drive with:

cd /Volumes/untitled/

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.

Configure Phone

Before you plug your phone into your USB port, put it USB developer mode. This lets us access the phone for debugging and flashing. To do this, go to the Settings application and navigate to Applications > Development, and turn on the "USB debugging" checkbox.

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.

To get this, you'll need to install the Android SDK starter package for your platform. Then run their package manager, $SDK_HOME/tools/android, and use the GUI to install "Android SDK Platform-tools".

adb will be installed to $SDK_HOME/platform_tools. Be sure to add directory is in your PATH. This can be done by adding the line

PATH=/data/myscripts:$PATH

to your ~/.basrc or equivalent.  Also, you may wish to run:

adb pull /system <backup target dir>/system

to back up the entire Android system partition on your phone. This will give you a copy of all the binary blobs for Android in case you later delete your B2G tree. 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

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:

On to the next step

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

Revision Source

<p>Before you can even get the code, so you can build Boot to Gecko. You'll 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 Mac OS X.</p>
<h2 id="Have_a_compatible_phone_or_use_emulators">Have a compatible phone or use emulators</h2>
<p>This is important. Even though we support several phones, some of them are available in multiple variations, and only select variations of them may be supported. In addition, some devices are supported better than others. At this time, the following devices have Firefox OS ports available:</p>
<h3 id="Tier_1">Tier 1</h3>
<p>Tier 1 devices are those which are being actively supported as a primary target for development. Features will typically arrive, and bugs will be fixed, first for these devices.</p>
<dl>
  <dt>
    Otoro</dt>
  <dd>
    Otoro is a phone being used as a test and development platform as a low-to-midrange smartphone. Most core Firefox OS developers are working on Otoro.</dd>
  <dt>
    <a href="/en-US/docs/Mozilla/Boot_to_Gecko/Pandaboard" title="/en-US/docs/Mozilla/Boot_to_Gecko/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/Boot_to_Gecko/Using_the_B2G_emulators" title="/en-US/docs/Mozilla/Boot_to_Gecko/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.</dd>
  <dt>
    <a href="/en-US/docs/Mozilla/Boot_to_Gecko/Using_the_B2G_desktop_client" title="/en-US/docs/Mozilla/Boot_to_Gecko/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/Gecko" title="/en-US/docs/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/Boot_to_Gecko/Introduction_to_Gaia" title="/en-US/docs/Mozilla/Boot_to_Gecko/Introduction_to_Gaia">Gaia</a> user experience inside it.</dd>
</dl>
<p>You can, of course, build the <a href="/en-US/docs/Mozilla/Boot_to_Gecko/Using_the_B2G_desktop_client" title="en-US/docs/Mozilla/Boot_to_Gecko/Using_the_B2G_desktop_client">desktop client</a> or one of the <a href="/en-US/docs/Mozilla/Boot_to_Gecko/Using_the_B2G_emulators" title="en-US/docs/Mozilla/Boot_to_Gecko/Using_the_B2G_emulators">emulators</a> without a phone.</p>
<h3 id="Tier_2">Tier 2</h3>
<p>The tier 2 devices are generally functional and many developers, especially app developers, are using them, so they tend to pick up changes secondarily.</p>
<dl>
  <dt>
    <a class="link-https" href="https://en.wikipedia.org/wiki/Nexus_S#Variants" title="https://en.wikipedia.org/wiki/Nexus_S#Variants">Samsung Nexus S</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>These devices are those for which Firefox OS can be built but are not being actively worked on on a regular basis by core developers, so their reliability and feature set may lag noticeably behind the tier 1 and even tier 2 devices.</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>
    I'm not currently aware of any variations that are not compatible.</dd>
</dl>
<div class="warning">
  <strong>Important</strong>: Only devices running <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>
<h2 id="Requirements_for_Linux">Requirements for Linux</h2>
<p>To build on Linux, you'll need to have a system configured with:</p>
<ul>
  <li>An installed Linux distribution (we recommend Ubuntu 11.10, and a 64-distribution is preferable).</li>
  <li>At least 4 GB of swap space.</li>
  <li>At least 25 GB of available hard disk space.</li>
</ul>
<p>This is more than the bare minimum, but you'll find after a while that you'll need the resources.</p>
<p>It's possible to use other distributions, but we recommend this one just to ensure everything works as expected.</p>
<p>You will also need the following tools installed:</p>
<ul>
  <li>autoconf-2.13</li>
  <li>git</li>
  <li>ccache</li>
  <li>gcc/g++, and you will need g++ multilibs</li>
  <li>bison</li>
  <li>flex</li>
  <li>32-bit ncurses (libncurses5-dev on Ubuntu/Debian and lib32ncurses5-dev on Ubuntu/Debian x64)</li>
  <li>32-bit zlib (ia32-libs and lib32z1-dev on Ubuntu/Debian)</li>
  <li>foo</li>
  <li>make</li>
  <li>curl</li>
  <li>bzip2</li>
  <li>heimdall (<strong>if building for the Samsung Galaxy S2</strong>; see {{ anch("Installing heimdall") }})</li>
</ul>
<div class="note">
  <strong>Note:</strong> When building on 64-bit Ubuntu, you may find that you need to add symlinks for the 32-bit versions of <code>libX11.so</code> and <code>libGL.so</code>; to do so, go into <code>/usr/lib/i386-linux-gnu</code> and create symlinks from <code>libX11.so</code> to <code>libX11.so.6</code> and from <code>libGL.so</code> to <code>mesa/libGL.so</code>.</div>
<h2 id="Requirements_for_Mac_OS_X">Requirements for Mac OS X</h2>
<p>To build Firefox OS on Mac OS X, you need to <a class="external" href="http://itunes.apple.com/us/app/xcode/id497799835?mt=12" title="http://itunes.apple.com/us/app/xcode/id497799835?mt=12">install Xcode</a>, which is available through the Mac App Store.&nbsp; On Xcode version 4.4.1+ (that is, Mac OS X10.8 "Mountain Lion"), open Xcode, under the Downloads tab, under the Components button, click Install on the Command Line Tools.&nbsp; On Xcode pre-version 4.4.1 (OS X 10.7 "Lion"), be 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>
<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>
<p>Then you need to open a terminal and run this command in the terminal; this will pull and run a bootstrap script that makes sure you have all prerequisites met.</p>
<pre>
curl -fsSL https://raw.github.com/mozilla-b2g/B2G/master/scripts/bootstrap-mac.sh | bash
</pre>
<p>This will check to see if you have all the things you need to be able to build the emulator, and will prompt you for permission to install anything you're missing. The items this script will check for and install for you are:</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>
<div class="note">
  <strong>Note:</strong> If you have already upgraded to Xcode 4.4 and get the message that Xcode is outdated, check the Xcode path with:
  <pre>
xcode-select -print-path</pre>
  If it still points to <code>/Developer</code> you can update the path with:
  <pre>
sudo xcode-select -switch /Applications/Xcode.app</pre>
  Next to that be sure that you have the Mac OS X 10.6 SDK available at:
  <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 the Xcode 4.3 DMG file which is available at the <a class="external" href="https://developer.apple.com/downloads/index.action">Apple Developer</a> portal. You can use the utility Pacifist to extract the 10.6 SDK. Be sure to add a symlink to it to the <code>/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/</code> directory.</p>
  <p>If you are building on OS X 10.8 "Mountain Lion" (Xcode 4.4.1 or later) and encounter the following error:</p>
  <pre>
external/qemu/android/skin/trackball.c:130:25: error: 'M_PI' undeclared (first use in this function)</pre>
  Edit the file: <code>B2G/external/qemu/makefile.android</code> and add in line 78:<br />
  <br />
  <pre>
MY_CFLAGS += -DM_PI=3.14159265358979323846264338327950288&nbsp;&nbsp; #/* B2G_fix: not finding M_PI constant */
</pre>
</div>
<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>
<div class="note">
  <strong>Note:</strong> Mac OS X uses a case insensitive filesystem by default, which will prevent you from building Firefox OS down the road (<strong>EDITOR'S NOTE: I have never had a problem with this)</strong>.&nbsp; You should create a case sensitive sparse disk image work from within that directory.&nbsp; To buld the case sensitive disk image:</div>
<pre>
hdiutil create -type SPARSE -fs 'Case-sensitive Journaled HFS+' -size 40g ~/firefoxos.dmg</pre>
<p>Mount the drive with:</p>
<pre>
open ~/firefoxos.dmg</pre>
<p>Change into the mouted drive with:</p>
<pre>
cd /Volumes/untitled/</pre>
<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.</p>
<h2 id="Configure_Phone">Configure Phone</h2>
<p>Before you plug your phone into your USB port, put it USB developer mode. This lets us access the phone for debugging and flashing. To do this, go to the Settings application and navigate to Applications &gt; Development, and turn on the "USB debugging" checkbox.</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>To get this, 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. Then run their package manager, <code>$SDK_HOME/tools/android</code>, and use the GUI to install "Android SDK Platform-tools".</p>
<p><code>adb</code> will be installed to <code>$SDK_HOME/platform_tools</code>. Be sure to add directory is in your <code>PATH</code>. This can be done by adding the line</p>
<pre>
PATH=/data/myscripts:$PATH</pre>
<p>to your ~/.basrc or equivalent.&nbsp; Also, you may wish to run:</p>
<pre>
adb pull /system &lt;backup target dir&gt;/system
</pre>
<p>to back up the entire Android system partition on your phone. This will give you a copy of all the binary blobs for Android in case you later delete your B2G tree. 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>
<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="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/Boot_to_Gecko/Preparing_for_your_first_B2G_build" title="en-US/docs/Mozilla/Boot_to_Gecko/Preparing_for_your_first_B2G_build">fetch the Firefox OS code</a>!</p>
Revert to this revision