Preparing for your first B2G build
Before you can build B2G, you need to clone the repository and configure your build tree. This article explains how to do that.
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.
Note: If you're using OS X to build B2G OS for Flame see the Building B2G OS for flame on OSX MDN page.
If you run Archlinux, please also refer to this discourse topic.
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
(type "i" for inserting) and this lines:
[user] name = yourname email = email@example.com[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
- 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.
config.shor refer to the Compatible Devices page.
If your build target isn't listed, you should stop right now and help port B2G OS!
Important: Only devices running at least Android 4.3 (Jellybean, Kitkat and Lollipop) are compatible. Please check that your phone is running the latest compatible version, or these next steps will fail. Refer to the Compatible Devices page for more details.
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!
$ adb devices List of devices attached ABCXXXXXXX device
If no device is listed, check your UDEV rules.
Note: If you have permission issues, check that your screen is unlocked and that you have authorized access to your phone. You see a message on your device for that. If the issue persists used
adb root and
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
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).
At this point, you should be ready for Building B2G OS.
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.
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: if building against a custom Gecko in Mac OS X, the mozilla-central directory must be in a case sensitive file system.
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.
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.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 "
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.
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/
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.
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