The make command is used inside the Gaia repo to create a Gaia profile that can be loaded onto your device or run in a B2G Desktop build. This article looks in detail at the different make options available.
Note: There are many environment variables present in the Makefile. Do not depend on them as they may be removed in the future.
Created profiles are generally stored in the root of the gaia directory, for example /gaia/profile, and contain the following items:
defaults/: Directory containing default settings to be reloaded after you reset the phone.extensions/: Directory containing extensions.settings.json: Settings file.user.js: Another file containing more settings/preferences.webapps/: Directory containing all the web apps that are to be installed on the phone.
Note: When you've already made a profile and you want to build a new one, you must delete the existing profile directory before trying to generate a new one.
Default
make
This simply gives you an unbranded, non-debug build. For a branded build you need to use Official Mozilla branding make; for a debug build you need Debug make.
Push to device
make install-gaia make reset-gaia
With ADB (Android Debug Bridge) setup, these make targets will push Gaia to the device. install-gaia will just push updates of Gaia from your working directory to your device. reset-gaia will purge all existing configuration, profiles, web apps and database entries (a new settings database will be initialized) before pushing Gaia.
Note: Pushing Gaia to your device using make install-gaia / make reset-gaia builds Gaia with 1x resolution assets by default. To specify higher resolution assets you need to use the GAIA_DEV_PIXELS_PER_PX or GAIA_DPPX make options (see High resolution image assets for more details of these options.). When pushing Gaia to your device in this fashion, you should specify the relevant make option along with your device's scale factor, so for example make install-gaia GAIA_DEV_PIXELS_PER_PX=1.5 for a Flame device (or 2, or 2.5, etc; see the scale factor values in the table inside 512 icon for device display.)
Build specific apps
APP=system make APP=system make install-gaia
When a profile already exists, APP allows you to specify which app to re-package, instead of re-packing and re-pushing all the Gaia apps. Note that while this command pushes the new app package and the manifest, the manifest change (e.g. new permissions, keyboard layout declarations) will not get picked up by Gecko.
Specify custom profile folder
You can specify a custom directory to build your profile in, using PROFILE_FOLDER, for example:
PROFILE_FOLDER=profile-b2g-desktop make
Different device builds
There are a few make options that create builds for different devices, with different purposes.
Create a phone build of Gaia
GAIA_DEVICE_TYPE=phone make
This build gets apps from /gaia/build/config/phone/apps-engineering.list.
Create a tablet build of Gaia
GAIA_DEVICE_TYPE=tablet make
This build gets apps from /gaia/build/config/tablet/apps-engineering.list.
Creating a spark build
GAIA_DISTRIBUTION_DIR=distros/spark make reset-gaia
Installs spark on your device. The equivalent B2G build.sh option looks like this:
GAIA_DISTRIBUTION_DIR=distros/spark ./build.sh
Different types of build
There are a few make options that create different types of build, with different purposes.
Production make
PRODUCTION=1 make
This creates a production build of Gaia:
- Gaia is run as packaged apps, which are harder to debug, but are the best available state for apps in terms of available API permissions, etc.
- Test apps are not included in the build
- Remote debugging is turned off by default
- Lock screen is turned on (which in turn will cut USB connections)
- Marionette is turned off
- First time user experience is turned on
- Offline cache is used.
Note: You can also use the alias make production.
Debug make
DEBUG=1 make
The DEBUG variable runs Gaia as hosted apps on a built-in web server on a specific GAIA_PORT, rather than the default of packaged apps which have to be re-packaged after every change; this makes things easier to test. Launching the profile with the latest Firefox Nightly will also give you nice B2G specific panels on the Firefox Developer Tools.
In addition:
- Test apps are included in the build.
- Remote debugging is turned on by default.
- Lock screen is turned off (USB connections won't be interrupted.)
- Marionette is turned on, which is needed when running Gaia unit tests.
- First time user experience is turned off.
- Offline cache is not used, even if it is generated.
Note: There is currently a bug (bug 1180103) that causes Gaia debug profiles to render with an empty homescreen when run through the Firefox OS Simulator (through WebIDE, or whatever.) This can be worked around by building with DEBUG=1 DESKTOP=0 make instead (see Device debug make.)
Device debug make
DEVICE_DEBUG=1 make
This disables screen lock on the device, and enables debugging with the ADB tool, so is useful for device debugging.
In Firefox OS version > 1.2, specify this param when you want to debug Firefox OS webapps with WebIDE.
Debug desktop make
DEBUG=1 DESKTOP=0 make
This option creates a desktop debug version, for running inside B2G desktop.
Official Mozilla branding make
MOZILLA_OFFICIAL=1 make
Use this to make an official Mozilla-branded build.
Dogfood make
DOGFOOD=1 make
Dogfooding options and utilities are turned on, for example the Feedback app, which allows dog fooders to easily submit feedback on the OS.
System apps make
B2G_SYSTEM_APPS=1 make
This environment variable lets you push an app to /system/b2g instead of /data/local. You should use this when you work with a user build. This variable is automatically set when running make production. This can be used for install-gaia or reset-gaia too.
Distribution and market customization build
GAIA_DISTRIBUTION_DIR=./dir
Note: Read Market Customizations for more details.
Developer/debugging options
There are also make options for adding/removing features or changing settings, for debugging purposes.
Enable remote debugging
REMOTE_DEBUGGER=1
This enables remote debugging on the device, the same as using the option in the developer settings.
JavaScript optimization make
GAIA_OPTIMIZE=1 make
This triggers an optimization pass on Gaia's JavaScript, concatenating/compressing the files. This is automatically set when running make production. This can be used for install-gaia or reset-gaia too.
High resolution image assets
GAIA_DEV_PIXELS_PER_PX=1.5 make
Or with alias:
GAIA_DPPX=1.5 make
When packaging the app, this option replaces images with their *@1.5x.(gif|jpg|png) equivalents if such images exist. You need to use the above option as part of a standard make command, for example:
GAIA_DEV_PIXELS_PER_PX=1.5 make reset-gaia GAIA_DEV_PIXELS_PER_PX=1.5 make install-gaia
Gaia is currently targetting the following screen resolutions:
- qHD: ~540×960; device pixel ratio = 1.6875
- WVGA: ~480×800; device pixel ratio = 1.5
- HBGA (320x240); device pixel ratio = 1
use GAIA_DEV_PIXELS_PER_PX to make sure the images looks sharp on qHD and WVGA devices. see A pixel is not a pixel for more information about device pixels per css pixels.
Running integration tests
You can run integration tests on Gaia using make. See Gaia integration tests for details.
Running Raptor performance tests
You need to configure your device for running Raptor tests prior to actually running the tests. See Raptor for details.
make raptor
Low memory profile build
GAIA_MEMORY_PROFILE=low make
This variable generates a low memory profile version of Gaia, aimed at low memory devices like the Tarako.
Disable first time use experience (FTU)
NOFTU=1
Disable the FTU with this environment variable.
Disable lockscreen
You can disable the Firefox OS lockscreen using the NO_LOCK_SCREEN option, for example:
NO_LOCK_SCREEN=1 make
Reference Workloads
Reference workloads allow developers/testers to quickly install a large amount of data in several applications, typically on a newly-flashed phone.
The commands are (from the gaia directory):
make reference-workload-light
- 200 contacts
- 200 sms messages
- 50 dialer history entries
- 20 gallery images
- 20 songs
- 5 videos
make reference-workload-medium
- 500 contacts
- 500 sms messages
- 100 dialer history entries
- 50 gallery images
- 50 songs
- 10 videos
make reference-workload-heavy
- 1000 contacts
- 1000 sms messages
- 200 dialer history entries
- 100 gallery images
- 100 songs
- 20 videos
make reference-workload-x-heavy
- 2000 contacts
- 2000 sms messages
- 500 dialer history entries
- 250 gallery images
- 250 songs
- 50 videos
These targets accept the APP environment variable, or an APPS environment variable that should contain the app names separated by a space, e.g.:
APP=sms make reference-workload-light APPS="sms communications/contacts" make reference-workload-heavy
The apps available are:
APPS="gallery music video communications/contacts sms communications/dialer"
In order to install music (songs) with reference workloads, the utility mid3v2 must be installed. This utility can be installed with:
sudo apt-get install python-mutagen
If you run Fedora or RHEL instead, use:
sudo yum install python-mutagen
Documentation make
Gaia docs can be built, via jsdoc3. To generate these, you can use the following command:
make docs
Enabling IME layout and dictionaries
To enable keyboard IME layout and dictionaries enabled, use following command structure:
GAIA_KEYBOARD_LAYOUTS=en,zh-Hant-Zhuyin,el,de,fr,zh-Hans-Pinyin make
We currently don't ship all the layouts by default due to disk space concerns. Bug 1029951 is being work on to decouple shipped layouts and it's dictionaries (by offering dictionary download to the users).
Please look at the file build/config/keyboard-layouts.json to know all available layouts.