Building B2G OS

Updating your code

If this isn't your very first time building B2G, you might want to pull the latest code before you start to build. To do that, update both the B2G tools and the dependencies, using the following two commands:

git pull
./repo sync -d

The -d option switches the various projects HEAD back to their Android manifest revision (i.e the default mainstream repository version). It is helpful if you made modifications to the repos (and have associated source changes) but you need to revert back to the master version temporarily. It will indeed leave your stagnant or working directory changes untouched (see the following SO question for the full explanation). If you did not touch the source code, you can use the normal command:

git pull
./repo sync

You can update a specific  target's repository by specifying its name:

./repo sync gaia

The repo command has other options available that might be interesting; repo help will provide with a lot of information.

Building Boot to Gecko

To build Boot to Gecko, simply use the build.sh tool:

cd B2G
./build.sh

Time for another coffee break, or possibly a nap (especially if this is your first build, it takes about 30 min on a Core i7 with 8GB of RAM). As in the configure step on the previous page, if you are using a directory of previously-extracted Android system files, you should set ANDROIDFS_DIR before running build.sh.

Building specific modules

If you want to build just a particular module, such as Gecko, you can specify it by name:

./build.sh gecko

In order to refresh only one application, you can build only gaia module by using the BUILD_APP_NAME environment variable:

BUILD_APP_NAME=calendar ./build.sh gaia

To get a list of the modules you can build, you can do:

./build.sh modules

Setting the number of processor cores to use

By default, the B2G build scripts use the number of cores your system has plus twice the number of parallel tasks to run. You can change this by specifying the -j parameter when running build.sh. This can be handy if you're using your system for other things while building in the background and need to reduce CPU load a bit. It's also handy when you're having build problems, as it can make reading error output from the build process easier if you have just one task going at a time!

For example, to build using just two parallel tasks:

./build.sh -j2

The most common use case for this, however, is to prevent builds from running in parallel at all. This makes the output of the process much easier to read, making it easier to sort out build problems. To do this:

./build.sh -j1

Building multilocale

To create a multilocale build, do the following:

1. Determine which Gaia languages file to use. We're currently using locales/languages_dev.json and locales/languages_all.json as our Gaia languages files.
2. Clone the appropriate locales from https://hg.mozilla.org/gaia-l10n into a directory; we use gaia-l10n/. You could use the locales/ directory . You'll need to clone a repo for each locale listed in the languages file.
3. In your environment, set LOCALE_BASEDIR to the absolute path of the directory in step 2. Set LOCALES_FILE to the absolute path of the file in step 1.
4. Also, you can set a GAIA_DEFAULT_LOCALE if you want to set a default locale.

cd gaia/locales/
hg clone https://hg.mozilla.org/releases/gaia-l10n/v2_5/es

export LOCALE_BASEDIR=$PWD/locales
export LOCALES_FILE=$PWD/locales/languages_dev.json
export GAIA_DEFAULT_LOCALE=es

And the languages-dev.json could be replaced by your own languages-own.json path, which could formed like this. You would need to add an entry per each repo cloned in your locales directory.:

{
  "en-US"     : "English (US)",
  "es"        : "Español"
}

Since bug 884752 landed (November 2013), to add keyboard layouts (if available in Gaia), you can use parameter GAIA_KEYBOARD_LAYOUTS. 

Bug: https://bugzilla.mozilla.org/show_bug.cgi?id=884752

Layouts: https://github.com/mozilla-b2g/gaia/tree/v1.2/keyboard/layouts

For example, to add Spanish and Italian keyboard layout, run the previous command adding

  GAIA_KEYBOARD_LAYOUTS=en,es,it

At this point  Gaia is ready to flash in the phone for the first time. Connect the phone and make sure Remote Debugging is checked in Settings > Device Information > More Information > Developer.  You only need to do this once, for your own build of Gaia will have that pref turned on thanks to REMOTE_DEBUGGER=1:

 make clean && make production LOCALES_FILE=locales/languages-own.json

or

 rm -rf out objdir-gecko && LOCALES_FILE=locales/languages-dev.json ./build.sh

Building an official-style engineering build

To build an "official"-style engineering build like the ones published by Mozilla, you'd need to use the following options on the command line:

VARIANT=eng MOZILLA_OFFICIAL=1 B2G_SYSTEM_APPS=1 GAIA_OPTIMIZE=1 B2G_UPDATER=1 B2G_UPDATE_CHANNEL=default MOZ_TELEMETRY_REPORTING=1 MOZ_CRASHREPORTER_NO_REPORT=1 LOCALES_FILE=locales/languages_all.json GAIA_KEYBOARD_LAYOUTS=en,pt-BR,es,de,fr,pl,zh-Hans-Pinyin,zh-Hant-Zhuyin,en-Dvorak ./build.sh

The parameters are explained below:

Building a blob free full system zip

B2G OS Master Branch Only

You can build a blob-free system zip that can be used to convert a supporting already running Android device into a B2G OS device, solving the long standing problem of not being able to distribute builds because of their copyrighted blobs. We are enabling this on a device-by-device basis, with only the Flame and Z3/Z3 Compact phones being supported initially.

Such a zip is built using the following option:

./build.sh blobfree

This produces a zip file composed of:

• A distribution zip with all the partitions ready but not as image files (BOOT, RECOVERY and SYSTEM directories.)
• A devices.json file describing supported devices with adb properties and fastboot variables to read from and assert support in a live device.
• Recovery fstab, to allow partition <-> image mapping.
• dt.img if required.
• Blob to system mapping, based on what is produced by extract-files.sh.

The resulting zip is intended to be used with the B2G installer addon (see bug 1166276.)

Known errors

"Build failed!"

 If you get a general "Build failed" message, you should always try reconnecting your phone to your computer; sometimes the phone can become unmounted for a variety of reasons.

Mountain Lion-specific build errors

external/qemu/android/skin/trackball.c:130:25: error: 'M_PI' undeclared (first use in this function)

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

/System/Library/Frameworks/IOKit.framework/Headers/usb/USB.h:797:9: error: too many #pragma options align=reset

Undefined symbols "_sqlite3_androidopt_handle_pragma" and "_sqlite3_androidopt_open"

This error appears if you are building on OS X 10.7 or newer with Xcode 4.5 or something newer. To fix this, apply the patch at https://groups.google.com/forum/#!msg/android-building/yAfPyUqCsiQ/7zvICk4GWjYJ to the external/sqlite/dist/Android.mk file.

KeyedVector.h:193:31: error: indexOfKey was not declared in this scope

This error appears when your gcc version is too recent, although this should no longer be an issue since we upgraded our build system to use newer GCC. If you need to set the build system to use an older GCC, you can do so: see Customizing with the .userconfig file for more information.

arm-linux-androideabi-g++: Internal error: Killed (program cc1plus)

If you see this message, it most likely means that free memory is lacking. Ensure there is enough free memory before running ./build.sh. It should run fine if your system has 4GB of RAM.

"...is referenced by DSO" error

While building the emulator, if you get /usr/bin/ld: out/host/linux-x86/obj/EXECUTABLES/triangleCM_intermediates/triangleCM: hidden symbol `_XGetRequest' in out/host/linux-x86/obj/STATIC_LIBRARIES/libSDL_intermediates/libSDL.a(SDL_x11dyn.o) is referenced by DSO.

You can get this with some versions in binutils. If you run Debian Stable, you can use the gold linker by installing the package binutils-gold. Note that the gold linker is already installed by binutils, but it's not used by default; binutils-gold does just that.

error: device not found

If you the message "error: device not found" at the beginning of ./build.sh, for example as part of this error:

Blob setup script has changed, re-running
Backing up system partition to backup-flame
error: device not found
Pulling files from ../../../backup-flame
cat: ../../../backup-flame/system/build.prop: No such file or directory
cat: ../../../backup-flame/system/build.prop: No such file or directory
Invalid system backup - Wrong base version found.

Do this:
1. Delete backup-flame
2. Flash your device with KK based images from the vendor
3. Try building again

> Build failed! <

In that case you need to make sure that your device is accessible with adb, so that it shows up when you run adb devices. Your device has to be connected, adb debugging needs to be enabled in the developer menu, and you may need to turn off screen locking so that the device is accessible even when it's locked. This is done by unchecking "Lock Screen" in the "Screen Lock" section in the  Settings app.

If you get build errors while the build system is running tests

Sometimes (especially after build tool or operating system updates) you'll get weird errors like this when the build system runs its post-build tests:

Generating permissions.sqlite...
test -d profile || mkdir -p profile
run-js-command  permissions
WARNING: permission unknown:offline-app
WARNING: permission unknown:indexedDB-unlimited
build/permissions.js:122: NS_ERROR_UNEXPECTED: Component returned failure code: 0x8000ffff (NS_ERROR_UNEXPECTED) [nsIPermissionManager.add]
make[1]: *** [permissions] Error 3
make: *** [gaia/profile.tar.gz] Error 2

In this situation, try deleting the gaia/xulrunner-sdk directory and re-pulling the code:

rm -r gaia/xulrunner-sdk

This deletes the downloaded, precompiled copy of XULRunner that the build system retrieves automatically; on your next build, a new copy of XULRunner will be automatically retrieved.

Cannot fetch platform/libcore

If you tried to configure your B2G build for Nexus S (./config.sh nexus-s) and got an error related to libcore, it is because of a problem with the linaro git that feeds into this. To fix this, checkout the B2G manifest like so:

git clone https://github.com/mozilla-b2g/b2g-manifest.git

Edit the nexus-s.xml file in this repo, replacing the linaro git entry with a reference to the aosp entry, which should read like so:

<default revision="refs/tags/android-4.0.4_r1.2"
              remote="aosp"
              sync-j="4" />

Commit these changes (git commit -a) and then change the config.sh file in the master branch of the main B2G repo that you checked out to point to your modified local manifest instead of the Mozilla one:

GITREPO=${GITREPO:-"file:///home/path/to/my/b2g-manifest"}

clang errors when building with Xcode 5 on Mac

If you are building on Mac OS X 10.8 with Xcode 5, you may see errors like the following:

clang: error: argument unused during compilation: '-include system/core/include/arch/darwin-x86/AndroidConfig.h'
clang: error: argument unused during compilation: '-U DEBUG'
clang: error: argument unused during compilation: '-U DEBUG'
clang: error: argument unused during compilation: '-MF out/host/darwin-x86/obj/EXECUTABLES/obbtool_intermediates/Main.d'
make: *** [out/host/darwin-x86/obj/EXECUTABLES/obbtool_intermediates/Main.o] Error 1

This is because Xcode 5 changes the g++ compiler in /usr/bin, which breaks the build process if you try to use it to compile. In order to work around the problem, edit the following line in build/core/combo/HOST_darwin-x86.mk:

HOST_CXX := g++

to

HOST_CXX := g++-4.7
ifeq (,$(wildcard /usr/local/bin/g++-4.7))
 HOST_CXX := g++
endif

Next, you have  to uninstall gcc, using brew (this assumes you've run the Mac OS bootstrap script — if not, you'll need to complete that step before continuing):

brew uninstall gcc-4.7

Now reinstall gcc with multilib and c++ support:

brew install --enable-cxx https://gist.github.com/artlogic/6988658/raw/aeb9d1ea098274ad3f3fe2637b9df7f308a8a120/gcc-4.7.rb

Make sure /usr/local/bin is on your PATH. You can do this temporarily by typing the following into the command prompt:

export PATH=/usr/local/bin:$PATH

You can make the above change permanent by adding it to the .bash_profile file in your home directory.

After you've set your PATH, make sure you can run both of the following commands:

gcc-4.7 -v

g++-4.7 -v

If either of these commands fail, you may need to relink your GCC using brew with the following command:

brew link --overwrite gcc-4.7

It's also possible that /usr/bin/c++ is not pointing at clang++ as it should be with Xcode 5 installed. You can determine if it is by typing the following:

ls -l /usr/bin/c++

It should return something that looks like this:

lrwxr-xr-x 1 root admin 7 Sep 19 11:40 /usr/bin/c++ -> clang++

If c++ is pointing at something other than clang++, update it with the following commands:

sudo rm /usr/bin/c++

sudo ln -s /usr/bin/clang++ /usr/bin/c++

"system/core/include/log/log.h:38:20: error: stdarg.h: No such file or directory"

This can occur if you are using the 10.6 SDK to build on Mac OSX 10.10, or some other SDK configuration that is not supported on the build config you are trying to build. See bug 1071266 for more details.

cp: cannot stat '../../../backup-flame/system/lib/libalsa-intf.so': No such file or directory

The symptom here is that the build system is trying to use a file from your backup directory, but this file is missing. Such issues can have several causes.

1. The USB connection is broken while the script pulls data from device to computer.
2. You're building for the wrong target (wrong device or wrong underlying Android version).
3. You don't have the base build the script expects.

We'll explore these causes in more detail in the below subsections.

The USB connection is broken while pulling data

When building, if the backup directory doesn't exist, the script will automatically start fetching the files from your attached device. At the end of this process you should see lines similar to the following:

143 files pulled. 0 files skipped.
3003 KB/s (512036044 bytes in 30.662s)

If you see pulling messages from adb (lines starting with pull) but don't see this, this means the connection was broken before completion. In this case you should delete your backup directory and try building again.

Note: Some base builds will disable adb when the phone is locked. If that's the case for you, you'll need to disable screenlock so that it doesn't lock itself.

You're building for the wrong target

The target is the parameter you gave to the config.sh script in the previous step. To check your configured target, just run:

$ cat .config

And you should get an output like the following:

...
DEVICE_NAME=flame-kk
PRODUCT_NAME=flame

The DEVICE_NAME is what you're looking for. For example, current flame builds should use flame-kk, not flame.

If the DEVICE_NAME is wrong, then you need to reconfigure using config.sh, delete your current backup directory (backup-flame for the flame), and rerun the build script.

Emulator build issues

If you are making an emulator build, you need to pay attention to these issues:

The build-system for the emulator builds both 32bit and 64bit versions of the emulator. As the emulator depends on OpenGL, this means that you need to have both 32bit and 64bit versions of OpenGL libraries installed on your system. See the discussion in bug 897727.

There are two ways that you can solve this problem:

Solution #1: have both 32 bit and 64 bit OpenGL libs installed, with the right symlinks

If your Linux distro has multilib packages for OpenGL libraries, you can attempt to install them. You might then have to manually create some symlinks.

For example, here is the situation for Ubuntu 12.04 LTS x86-64. On this distribution, the libgl1-mesa-dev package cannot be installed simultaneously in x86-64 and i386 versions, but you can have the following combination of packages simultaneously installed:

sudo apt-get install libgl1-mesa-dev libglapi-mesa:i386 libgl1-mesa-glx:i386

After having run this command, you will still have to manually create some symlinks for the emulator build to succeed:

sudo ln -s /usr/lib/i386-linux-gnu/libX11.so.6 /usr/lib/i386-linux-gnu/libX11.so
sudo ln -s /usr/lib/i386-linux-gnu/mesa/libGL.so.1 /usr/lib/i386-linux-gnu/libGL.so

Solution #2: just patch the emulator so it only builds 64 bit

Just apply this patch to the sdk/ Git repository found under the B2G repo. This will cause the B2G emulator to only attempt to build the 64 bit emulator if you're on a 64 bit system, thus avoiding any multilib issues. The 32 bit emulator is unused on a 64 bit system. This is the simplest solution, until this patch eventually bit-rots.

Android can only be built by versions 3.81 and 3.82.

For Ubuntu you can compile an older version by downloading this version

Install using the following:

tar xvzf make-dfsg_3.81.orig.tar.gz                             
cd make-dfsg-3.81.orig/
./configure
make
make check
make install
echo alias make=\'$(pwd)\' >> B2G/.userconfig

Next steps

After building, your next step depends on whether you built Boot to Gecko for the emulator or for a real mobile device; see the following articles for details:

• Using the B2G emulators
• Using the B2G desktop client
• Installing Boot to Gecko on a mobile device
• Installing Boot to Gecko on a pandaboard

Submitting bugs on B2G/B2G OS/Gaia

Once you've got a B2G/B2G OS build running, you'll probably want to start to file bugs against this specific version, so the B2G OS community can improve things as effectively as possible. You'll want to file the bug on Bugzilla, under the "B2G OS" project, but you should include version specifics:

1. To start with, tell us the major version number, e.g. 1.4.0.0-prerelease. This can be found on the device under Settings > Device Information.
2. You can provide more specific version identifiers by  returning the current hashes from the gaia and gecko repositories. This can be done like so:

   #!/bin/bash
   (cd gaia;  echo "gaia  $(git rev-parse HEAD)")
   (cd gecko; echo "gecko $(git rev-parse HEAD)")