Please note, this is a STATIC archive of website developer.mozilla.org from 03 Nov 2016, cach3.com does not collect or store any user information, there is no "phishing" involved.

Customizing build-time apps

As a developer or device vendor, you will want to customize the apps that appear on a Firefox OS device at first-run for a variety of reasons. This article explains the different mechanisms for doing so.

App locations inside Gaia

The apps that run on Firefox OS are all contained within the Gaia source tree, in one of two locations:

  • gaia/apps/: This is where the system default apps are found, such as calendar, email, settings, etc.
  • gaia/dev-apps: This is where other apps are found, such as those included in the customization process.

If you want to omit from/add to these apps in your build of Gaia/B2G, you can do this in a few different ways, as detailed below.

Brute force customization method

The "brute force" method is to simply delete the apps you don't want to be present at build time, before building.

Editing config lists

The more refined method is to edit the apps-*.list files (found in the different device directories found inside gaia/build/config/, such as phone/ and tablet/) to include the paths to the apps you want to include at build time. For example, gaia/build/config/phone/apps-production.list looks something like this:

apps/bluetooth
apps/bookmark
apps/browser
apps/calendar
apps/callscreen
etc.

Note that you can also specify use of all the apps in a directory, like so:

apps/*

The mechanism for choosing which apps-*.list file is used during the build to determine the available apps is contained inside gaia/Makefile, and looks something like this:

GAIA_DEVICE_TYPE?=phone
  ...
GAIA_APP_TARGET?=engineering
  ...
ifeq ($(MAKECMDGOALS), demo)
GAIA_DOMAIN=thisdomaindoesnotexist.org
GAIA_APP_TARGET=demo
else ifeq ($(MAKECMDGOALS), dogfood)
DOGFOOD=1
else ifeq ($(MAKECMDGOALS), production)
PRODUCTION=1
endif
  ...
ifeq ($(PRODUCTION), 1)
GAIA_OPTIMIZE=1
GAIA_APP_TARGET=production
endif

ifeq ($(DOGFOOD), 1)
GAIA_APP_TARGET=dogfood
endif
  ...
ifndef GAIA_APP_CONFIG
GAIA_APP_CONFIG=build$(SEP)config$(SEP)apps-$(GAIA_APP_TARGET).list
endif

Initially, the GAIA_APP_TARGET variable is set to engineering and the GAIA_DEVICE_TYPE variable is set to phone, so by default building Gaia from source will use the gaia/config/phone/app-engineering.list (which includes all the tests, demos, etc.)

To specify usage of a different apps list you specify different options when running the make command. To build with gaia/build/config/phone/apps-production.list, for example, you'd use

PRODUCTION=1 make

If you specifically build with DEMO=1 specified, then it will use apps-demo.list. If you specifically build with DOGFOOD=1 specified, then it will use apps-dogfood.list.

You can completely override the decision by editing GAIA_APP_CONFIG in the gaia/Makefile, and providing your own apps-*.list file.

gaia/Android.mk contains these lines:

ifneq ($(filter user userdebug, $(TARGET_BUILD_VARIANT)),)
GAIA_MAKE_FLAGS += PRODUCTION=1
B2G_SYSTEM_APPS := 1
endif

When you build, if VARIANT=user or VARIANT=userdebug are set (these wind up getting reflected in the TARGET_BUILD_VARIANT variable), PRODUCTION=1 is automatically set when building Gaia.

Note: Find out what other make options are available in our make options reference.

Using Market customizations

The third, and most refined (but most complex) method is to use customizations. These allow you to specify build-time customization instructions in separate difrectories, without modifying the core Gaia repo. You can include your own customizations in distinct directories, or use the preexisting directories that come with the source.

For example, specifying the location of the customization sample with the GAIA_DISTRIBUTION_DIR environment variable, like this:

GAIA_DISTRIBUTION_DIR=<DISTRIBUTION_PATH> make production

More customizations sample for distribution mechanism, please refer to https://github.com/mozilla-b2g/gaia/tree/master/customization

Customizations is its own separate topic entirely. To learn more about it, read our Market Customizations guide.

Note: If you want to include custom external apps as part of your Gaia build, you need to build them in a specific way, and then place them into the gaia/dev-apps/ folder. Read Building Prebundled web apps to find out more.

Important: If you are a device vendor creating a custom B2G/Gaia build for distribution, you need to satisfy certain criteria before you are allowed to include the Firefox Marketplace app on your phones/tablets/etc. Contact Mozilla for more details.

 

Document Tags and Contributors

 Contributors to this page: chrisdavidmills, SphinxKnight, PYChen, rbrandao
 Last updated by: chrisdavidmills,