Your Search Results

    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:


    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:

    ifeq ($(MAKECMDGOALS), demo)
    else ifeq ($(MAKECMDGOALS), dogfood)
    else ifeq ($(MAKECMDGOALS), production)
    ifeq ($(PRODUCTION), 1)
    ifeq ($(DOGFOOD), 1)
    ifndef GAIA_APP_CONFIG

    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/ contains these lines:

    ifneq ($(filter user userdebug, $(TARGET_BUILD_VARIANT)),)
    B2G_SYSTEM_APPS := 1

    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:


    More customizations sample for distribution mechanism, please refer to

    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: rbrandao, PYChen, chrisdavidmills
    Last updated by: PYChen,
    Hide Sidebar