Preparing for your first B2G build

Depending on your internet connection, the configuration steps may take several hours to download everything you need to build B2G OS. 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 B2G 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

We have several useful tools for building B2G OS, all contained in a single repository. The first step is to download these tools with git to create your working directory:

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

If you run in to a UnicodeEncodeError: ascii codec error here try to set your git user with

 vim ~/.gitconfig

(type "i" for inserting) and this lines:

[user]
       name = yourname
       email = youremailaddress@url.tld
[color]
       ui = auto

hit the "esc" button and quit with ":wq"

• Configure B2G for the device :

$ ./config.sh <device> 

ie device = flame-kk or aries

• Build and flash B2G
• plug in your device that has the android base or firefox os base build

$ ./build.sh
$ ./flash.sh

Notes:

• If you get an error about a mismatched base build at the build step you don't have the required existing version of Android/B2G on your device. You'll need to flash the version of Android specified by the build script or get hold of a backup-aries folder.

If your build target isn't listed, you should stop right now and help port B2G OS!

Configuring a build for a mobile device

Proprietary Blobs

When you install B2G OS to a device you will need to include a set of proprietary blobs. These are extracted from the device when you run your first build, but we recommend that you also make a full backup to a safe place for future reference. Once B2G OS is installed, there is no way to recover these files!

Ensure you device has Remote Debugging enabled in Developer settings. Confirm your device is visible with the adb devices command, you should see something similar to this:

$ adb devices
List of devices attached
ABCXXXXXXX       device

If no device is listed, check your UDEV rules.

Back up the phone's partitions with the adb pull command:

adb pull /system <backup target dir>/system

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

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

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

• Check you have granted root permissions 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 For Linux: configure the udev rule for your phone).

On to the next step

At this point, you should be ready for Building B2G OS.

Advanced Configuration options

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 have a backup of the system partitions, 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 look for an existing backup in a folder, backup-<target>/system; you don't need to specify the directory if you place the files in this location.

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