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 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.
You might want to have a side task prepared, or a friend available to go for a coffee with, while you are running the B2G config and build steps. They can take a bit of time (config alone takes around 45min using a fast Internet connection, build is about 30 min on a Core i7 with 8GB of RAM).
If you're using OS X to build Firefox OS for Flame see the Building Firefox OS for flame on OSX MDN page.
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:
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:
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-4-kk - nexus-5 - nexus-s - nexus-s-4g - flo (Nexus 7 2013) - otoro - unagi - inari - keon - peak - leo - hamachi - helix - wasabi - fugu - tarako - tara - dolphin - pandaboard - vixen - flatfish - flame - flame-kk - rpi (Revision B) - 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:
Note: If you get an error message like:
UnicodeDecodeError: 'ascii' codec can't decode byte 0xc3 in position 9: ordinal not in range(128)
It may be because you have accent or other unsupported characters in the full path of the current directory, like '/home/username/Téléchargements/B2G/'. Move the B2G repo somewhere else. Cf. : http://stackoverflow.com/questions/18049320/repo-init-unicodedecodeerror-on-ubuntu-13-04
On OSX, a similar error may occur like so:
File "/Path/to/B2G/.repo/repo/git_refs.py", line 155, in _ReadLoose1 ref_id = ref_id.decode() UnicodeDecodeError: 'ascii' codec can't decode byte 0xd0 in position 578: ordinal not in range(128)
One possible workaround for this is to go to line 155 of the git_refs.py located at '/Path/to/B2G/.repo/repo' and change
fatal: manifest 'nexus-s.xml' not available, chances are that you simply have to specify the branch you want to use. See Building a branch for details.
error: manifest required for this command -- please run init, then changes are that the manifest file for the repo (located at
B2G/.repo/manifest.xml) wasn't created successfully. You should try running
config.shagain. If you are doing this for a new device you could add it to
config.shand then hand it your local manifest file like so:
./config.sh <device> -m path/to/manifest.
Near the start of the configuration you might need to set your identity (the one used by git) as well as the option for color usage. After this the process continues. For color selection, you can just select 'y' here, as you probably want a color build.
Note: it is possible for
config.sh to fail with git-related fetching errors such as the following :
Fetching projects: 95% (118/124)
error: Exited sync due to fetch errors
This appears to be caused by a connection error on the Android repo source repository. In this case, you will want to rerun
config.sh. After a short while, It will automatically resume where it left off. You might have do to this several times until it finally fetches all projects.
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:
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.
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: 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.
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.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 "
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/
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].