Preparing for your first B2G build

Depending on your internet connection, the configuration step takes a number of hours to download the files necessary to build FirefoxOS (with a mediocre 150 kBps connection, downloading gigabytes of Android repositories can take tens of hours).  Waiting is not as fun as doing, so after you have read through this page and have kicked off the configure script, consider using the time to set up and try out the Firefox OS simulator, begin familiarizing yourself with Documentation for app developers including Designing and Building an App, or familiarize yourself with the information on upcoming steps.

Clone B2G repository

The first step, before you can start your first build, is to clone the B2G repository. This will not fetch everything! Instead, it will fetch the B2G build system and setup utilities. Most of the actual B2G code is in the main Mozilla Mercurial repository.

To clone the repository, use git:

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

After cloning (which should only take a minute with a fast connection), cd into the B2G directory:

cd B2G

Configuring B2G for your device

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

./config.sh

This will display a list of the supported devices, like so:

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

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

If your device isn't listed, you should stop right now and either help port B2G to your device or wait until someone else does it. We'd prefer it if you help out!

This would be a good time for a coffee break, since at this point, you'll be doing your first pull of all the code needed to build Boot to Gecko. Running the device config step as indicated below can take a long time; you may stop it with Ctrl-C and restart it at a later time. If you think some part of the process may have been terminated without completing, run './repo sync' to repair any possible problems.

Configuring the B2G build for a mobile device

At this point, connect your device if it is not already connected; the configure process will need to access it.

If your device was listed in the results shown above, you can start the configure process by running config.sh again, this time specifying your device's name. For example, to build for the Samsung Google Nexus S, you would type:

./config.sh nexus-s

Near the start of the configuration you might need to set the option for color usage, then after this the process continues. You can just select 'y' here, as you probably want a color build.

Configuring a build using a system backup

If your phone no longer has Android on it, and your B2G tree doesn't have the binary blobs in it, but you wisely made a backup of the /system partition, you can perform the build on the system backup like this:

ANDROIDFS_DIR=<absolute path to parent dir of system dir> ./config.sh <target>

The build system will default to looking in someplace like backup-inari/system (depending on the device configuration); if you place the files in the expected place you won't need to specify the directory.

Note that if your phone always had Firefox OS on it to begin with and never ran Android, it's still fine to pull the /system partition per the above directions — this will give you the right files.

Configuring the B2G build for an emulator

If you want to build an emulator rather than on a real phone, you can specify emulator* to get an ARM device emulator, or emulator-x86* to build an x86 emulator. The latter is faster but not as accurate a representation of an actual mobile device and not as well supported; using it is not advised.

So, to build the ARM Jellybean emulator, for example, you would use the following command:

./config.sh emulator-jb

Near the start of the configuration you might need to set the option for color usage, then after this the process continues. You can just select 'y' here, as you probabaly want a color build.

By this point you should be ready to start the build, unless you need any of the more advanced information detailed below.

Beware that building for the emulator may fail on 64-bit Linux.

Building against a custom Gecko

There may be times that you want or need to build Boot to Gecko based on a different version of Gecko than the one that's used by default (as specified in the manifest). You can do so by editing the file .userconfig. For example, if you want to build against mozilla-central:

export GECKO_PATH=/path/to/mozilla-central
export GECKO_OBJDIR=/path/to/mozilla-central/objdir-gonk

Note that you can do this either before you pull the repository (i.e. before the config.sh step above) or at any later point.  You can also keep multiple builds (with debugging on or not, etc) by having multiple userconfig files (with different settings--each needs a different OBJDIR, of course) and making .userconfig a symlink that points to whichever config you want to build at the moment.

For more information, read Changing the Gecko source tree.

Building a branch

If you want to build for a branch other than the default branch (note: the default branch may not be "master"!), you will need to prefix your call to config.sh with a branch name, like this:

BRANCH=branch-name ./config.sh <device>

The branch names are pretty logical, and largely follow the names of the products/versions, so v1-train, v1.0.0, v1.0.1, v1.1, v1.1.0hd, v1.2, v1.3, v1.4, v2.0  and so on into the future. As an example, to build B2G Firefox 1.2, for the Arm emulator, you'd enter

BRANCH=v1.2 ./config.sh emulator

If you have run config.sh already, you can see the names of the branches, by going to B2G/.repo/manifests and doing "git branch -a" (this isn't populated unti then.) The branch name is given as the final token on the line, e.g. "v1-train" or "master":

  remotes/origin/master
  remotes/origin/v1-train
  remotes/origin/v1.0.0
  remotes/origin/v1.0.1

See Customization with the .userconfig file for additional customizations you can do.

Copying your B2G tree to a new machine

If you've previously set up the B2G tree and then gotten a new computer (lucky you!), you'll find your life will be much easier if you simply migrate your entire B2G tree from your old computer to your new one, rather than setting the whole thing up again. To do that, mount your old computer's drive onto your new computer, then do this:

rsync -a source/ dest/

Where source is the full path (including the trailing slash) of the source tree, and dest is where you want to put it (the trailing slash is also important!).

If you do this, you can skip all of the rest of this article and move right on to building.

Updating your B2G tree

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

git fetch origin
git checkout origin/master

You can check that these worked correctly by running:

git show HEAD

and checking that the commit shown matches the latest commit shown at: https://github.com/mozilla-b2g/B2G/commits/master

On to the next step

At this point, you should be ready for Building Firefox OS [en-US].