You can customize certain aspects of the build process by putting some bash code into your B2G source's .userconfig
file. This article looks at what you can achieve by making changes here, and how to do that.
The .userconfig
file isn't checked into source code control, so your changes won't be overwritten when you update your source tree. It needs to be created in the root of the B2G tree; that is, in the same directory as flash.sh
, build.sh
, and so forth. You should add this before you run your config and build steps.
The .userconfig
file, if it exists, is sourced by the load-config.sh
script, which is in turn sourced by these scripts: flash.sh
, build.sh
(through setup.sh
), run-gdb.sh
, run-emulator.sh
and tools/mach_b2g_bootstrap.py
. The run-*.sh
scripts use it to determine where Gecko is for your build. The mach_b2g_boostrap.py
script is used by every B2G related mach command.
Important: Your .userconfig
file should be in the root of your B2G source directory, not your home directory!
Changing the Gecko source tree
By default, the build uses the gecko tree, which is cloned from a tree in github. Some people like to use mozilla-inbound, or mozilla-central. To do this create your clone whereever you like and add a line to your .userconfig
which sets GECKO_PATH
, for example:
export B2G_DIR=${B2G_DIR:-$(cd $(dirname $0); pwd)} echo "B2G_DIR = ${B2G_DIR}" export GECKO_PATH=${B2G_DIR}/mozilla-inbound echo "GECKO_PATH = ${GECKO_PATH}"
Note: if building against a custom Gecko in Mac OS X, the mozilla-central
directory must be in a case sensitive file system or else GECKO_PATH
will be ignored. You can check whether the file system is case sensitive by running this in a Terminal window:
echo -n This file system is case->tmp; echo -n in>>TMP; echo sensitive>>tmp; cat tmp
Getting B2G_DIR
the way it is above allows your .userconfig
to work without having hard-coded paths.
Changing Gaia settings
Sometimes, you'd like to be able to change gaia settings. For example, enabling adb in a user build. The gaia Makefile passes in --override build/custom-settings.json
when calling build/settings.py
, so we can write some bash which will write {"devtools.debugger.remote-enabled": true}
into the custom-settings.json
file. We try to avoid changing custom-settings.json
if we don't need to, so we actually write into custom-settings.json.new
and if the contents differ from custom-settings.json
then we'll replace it.
export GAIA_PATH=${GAIA_PATH:-$(cd gaia; pwd)} export CUSTOM_SETTINGS="${GAIA_PATH}/build/config/custom-settings.json" cat > "${CUSTOM_SETTINGS}.new" <<EOF {"devtools.debugger.remote-enabled": true} EOF if [[ -f ${CUSTOM_SETTINGS} ]] && cmp "${CUSTOM_SETTINGS}" "${CUSTOM_SETTINGS}.new" >& /dev/null; then rm "${CUSTOM_SETTINGS}.new" else mv "${CUSTOM_SETTINGS}.new" "${CUSTOM_SETTINGS}" fi
Another easier way is to configure a build/config/custom-prefs.js
file in the Gaia working directory, so that means in gaia/build/config/custom-prefs.js
if you're in the B2G directory. See Gaia Build System Primer, Customizing the preferences.
Note: Currently the build is not smart enough to look in a different directory based on GAIA_PATH
. This is different from how GECKO_PATH
behaves. If you wish to use a separate Gaia clone you can manually run make from that directory.
Creating different build types
You can create many different types of Gaia build automatically upon running the make command, by setting various options in your .userconfig
— this section covers a number of different options.
Note: You can also set many different build options dynamically at build time by including different options along with the make command when you build. For a complete reference, see our make options reference article.
Creating production and engineering builds
To create different production builds (built with the final apps you'd want users to see) and engineering builds (built with additional test apps and other engineering features), you can add the following lines into .userconfig
:
PRODUCTION=1
On its own, this creates a production build. This can also be achieved on the fly by setting the production
make option.
Alternatively, there are variants, which set various levels of engineering capabilities:
VARIANT=user VARIANT=userdebug VARIANT=eng
The differences between these variants are as follows:
- The eng variant places the default apps in
/data
and includes many more apps than user/userdebug, for testing purposes. It also has Marionette enabled by default so you can run tests. This is the default value if no variant is specified. - The userdebug variant puts apps in
/system
, has Marionette enabled by default so you can run tests, and has the updater enabled, so you can get over-the-air (OTA/FOTA) updates. - The user variant places the default apps in
/system
and has the updater enabled, so you can get over-the-air (OTA/FOTA) updates.
Note: user and userdebug both imply PRODUCTION=1
when building locally for a real device/emulator.
Note: make production
is really a way to build a user version of Gaia and flash it to the device. Specifying a VARIANT
is the way to do this when building for Gaia in Nightly or B2G Desktop.
Creating a debug build
To build a debug build, put the following line in your .userconfig
file:
export B2G_DEBUG=1
This can be achieved on the fly at build time by including the DEBUG=1
make option.
Creating a profiling build
To enable profiling (for best results with the built-in (SPS) platform profiler), add the following to your .userconfig
file then rebuild:
export B2G_PROFILING=1
Important: Do NOT pair with B2G_NOOPT. The results will be meaningless!
Disabling the optimizer
To disable the optimizer (which may create builds that are easier to debug), add the following to your .userconfig
file then rebuild:
export B2G_NOOPT=1
Disabling First Time User experience
If you build and reflash a lot, going through the First Time User experience constantly can be annoying. You can disable this by adding the following to your .userconfig
:
export NOFTU=1
This can be achieved on the fly at build time by including the NOFTU=1
make option.
Building the updater and the update tools
By default the updater and the update tools are built only in userdebug and user builds.
You can force building the updater and the associated tools by adding the following to your .userconfig
file:
export B2G_UPDATER=1
Enabling Gaia developer mode
If you plan to develop apps or hack gaia, you can automatically set various usefull settings and preferences to ease working with the device. For example, it will automatically enable the remote debugging feature and disable the prompt when an incoming debugging connection starts.
What you need is the following export added to your .userconfig
:
export DEVICE_DEBUG=1
Enabling Valgrind
Valgrind is a debugging tool useful for debugging memory or threading issues with your application. For more information on running valgrind, see Debugging B2G using valgrind.
To use valgrind under B2G, add the following to your .userconfig
:
export B2G_VALGRIND=1
Changing the default host compiler
On some recent distributions that use GCC 4.7 or later as the default compiler you might need to specify an older version in order to be able to build, depending on your platform of choice. To do so add two lines to your .userconfig
file, setting the CC
and CXX
variables to set the alternate C and C++ compilers, respectively. For example to set the GCC 4.6 compiler on Ubuntu 12.10 use:
export CC=gcc-4.6 export CXX=g++-4.6
Or if you're using a version built from sources provide the full path to the exectuables:
export CC=/opt/gcc-4.6.4/bin/gcc export CXX=/opt/gcc-4.6.4/bin/g++
Specifying a custom Gecko object tree location
Once you start changing gecko source trees and other build options, you may want to also modify where your objects get stored (so, for example, all of your debug objects go into a different tree from your non-debug objects). So you might do something like:
export GECKO_OBJDIR=${GECKO_PATH}/objdir-gonk-debug
Using ${GECKO_PATH}
makes it easy to switch between different gecko trees (eg: central, beta, aurora, etc).
Keeping both debug and non-debug objects
You can use your .userconfig
file to switch back and forth between debug and release builds without having to rebuild everything each time!
export B2G_DIR=${B2G_DIR:-$(cd $(dirname $0); pwd)} echo "B2G_DIR = ${B2G_DIR}" export GECKO_PATH=${B2G_DIR}/mozilla-inbound echo "GECKO_PATH = ${GECKO_PATH}" export B2G_DEBUG=1 echo "B2G_DEBUG = ${B2G_DEBUG}" export GECKO_OBJDIR=${GECKO_PATH}/objdir-gonk if [[ "${B2G_DEBUG}" != "0" ]]; then export GECKO_OBJDIR=${GECKO_OBJDIR}-debug fi if [[ "${GECKO_PATH/*mozilla-inbound*/mozilla-inbound}" == "mozilla-inbound" ]]; then export GECKO_OBJDIR=${GECKO_OBJDIR}-m-i fi echo "GECKO_OBJDIR = ${GECKO_OBJDIR}"
The echo
commands help remind you what your current settings are. To switch between debug and release builds, simply change the value of B2G_DEBUG
on line 7.