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.
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.
The "brute force" method is to simply delete the apps you don't want to be present at build time, before building.
The more refined method is to edit the
apps-*.list files (found in the different device directories found inside gaia/build/config/, such as
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:
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
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
You can completely override the decision by editing
GAIA_APP_CONFIG in the gaia/Makefile, and providing your own
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=userdebug are set (these wind up getting reflected in the
PRODUCTION=1 is automatically set when building Gaia.
Note: Find out what other make options are available in our make options reference.
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.