Table of Contents
- Chapter 1 - Overview
- Chapter 2 - Get in touch with Gaia
- Chapter 3 - Gaia under the hood
- Chapter 4 - Build Script
Firefox OS, the frontier of web technologies, is the voyage of the Mozillans to explore strange new worlds, to seek out emerging and wild uninvented web technologies, and to boldly go where no man has been before!
Firefox OS is the fantacy land. It shows that everything is achievable via web technologies, and you, a web developer, can live with it happily ever after … oneday. The good thing is Firefox OS is open source: you can be the one make it a reality!
Beyond Web - GAIA FROM Above will introduce the Front End of Firefox OS - GAIA, by module and functionalities. The material in this book is mostly based on the studies of and sharing sessions from Taipei GAIA Platform(PE) and Device porting(DPE) team.
Since Firefox OS is evolving, this book is based on the master branch of Gaia (from v1.4 at 2014/12 to 3.0 2015/3).
Why I write this book
To develop a Mobile OS is a challenging task. To make Mobile OS by web technology is an ambitious and exciting goal. As the B2G and Gaia project evolve, I found the lack of documentation to help developers understand how constituents of B2G fit together. Many aspects of how the system works, such as how the system is booted or an app is launched, remain undocumented. The situation might scare developers away from start getting hands on this interesting project. As around top #30 gaia contributor, I take the action to write this book to help myself and potential contributors to learn deeply about how Gaia works.
Why bother reading this book
FIrefox OS is a truely open source platform based on a sophisticated web engine, Gecko, and is developed by the great open minds from Mozilla and the community. Many new Web APIs, tools, design patterns are invented and applied while web technology is unleashed to utilize mobile device capabilities. You may not want to miss the tide of modern mobile web platform.
Let’s start the journey.
Thanks Mozilla to bring the web as the platform to the community. Carriers and device vendors also play the key roles to make this open source platform delivered to amount of people.
The main author is Fred Lin who coordinates the book structure and the writing.
Related chapters are based on presentations and documents from:
- Gaia under the hood - Kanru Chen
- Build script - Yuren Ju
- System and window management - Alive kuo and Luke Chang
- Settings - Arthur chen
The awesome book cover is designed by Vit Lai.
Since the book is CC 2.0 shared-alike license, part of this book is available on MDN. Thanks Chris Mills for editing.
If you have any issue or any comments about this book, please go to the feedback section in book landing page and leave your comment there.
Chapter 1 - Overview
1.1 Firefox OS architecture
The main Firefox OS architecture is
- Application Layer : known as Gaia
- Platform Layer : known as Gecko
- Infrastructure Layer : known as Gonk
You may want to know the Firefox OS architecture better before you start developing Gaia. Here are introductory slides of the Firefox OS and Gaia development flow: Developing Firefox OS and FirefoxOS for developers. Also there’s an Overview and High Level Architecture that elaborates the Firefox OS Architecture more concisely.
Boot2Gecko (B2G) is the project name of Firefox OS. You can see it anywhere through Firefox OS related projects.
Firefox OS and
Firefox are branded names from Mozilla Foundation. Consult Mozilla before making a production device with such names. In unofficial version of Firefox OS, you will see
B2G OS instead of
Firefox OS on the settings app
device section if you are using the simulator or the development build.
1.2 Gecko Overview
Gecko is the core engine powering all Firefox and FirefoxOS versions. You may not know the fact that
every browser is like gecko. Since the sentence
like gecko is a build-in keyword in every internet connection messages. Search
[user-agent](http://en.wikipedia.org/wiki/User_agent#Format_for_human-operated_web_browsers) of any browser, you will find:
Since Gecko is the browser engine from the very first popular Netscape navigator. Internet Explorer and other browsers put this keyword in their user-agent messages. Now it’s in the W3C standard.
You can download Gecko source by following the guide. (Note: To build full Firefox OS you don’t have to download gecko separately)
Gecko is ported to several platforms via
port layer. For example, the Firefox Windows version adapts the
gecko port for Windows to build the browser with native look and feel.
In Gecko source there’s a
b2g/ folder that contains the adapter to gonk (gonk port) that unleashes mobile hardware capabilities to the web. Mozilla and the community will keep extending it to push the capability of Firefox OS and web standards.
1.3 Gonk Overview
Gonk is the device porting layer, which is an adapter between hardware and gecko. Gonk is a relatively simple Linux distribution that can be treated as a Gecko Port paired with Gecko porting layers.
Gonk includes the Linux kernel, userspace hardware abstraction layer (HAL), and other OEM specific libraries. Since different devices may have their specific chipsets and varied hardware specs, the Gonk layer may look pretty different for devices.
https://github.com/mozilla-b2g/B2G contains official support gonk ports for a variety of devices. You can treat it as a gonk repository. The list of supported devices is available in B2G/config.sh.
General gonk work includes porting to the specific board and make sure Gecko can work well on the device.
1.4 Gaia Overview
The Gaia functionalities can be roughly categorized into the following groups:
Including System, Settings, Lockscreen, Build script, Keyboard and IME, and Bluetooth apps.
The System app is the first web app loaded by Gecko during the Firefox OS bootup procedure. It bears numerous responsibilities that are essential for running the system, and are therefore out of scope of individual web apps.
Firefox OS’s window management functionality — including app life cycle and interaction, notifications, animations and much more — is handled by a specific part of the System app. This article looks at Firefox OS Window Management in detail.
The Settings app allows Firefox OS users to configure device settings, and responds to incoming activities (Web activities named
configure), which allows other apps to jump to different panels inside the Settings app to handle configuration as required (such as showing the wifi settings panel if no data connection is available.)
Keyboard is a special app which works closely with system. It handles layout and multiple input-method editors (IME).
Like other mobile platforms, Homescreen shows currently installed webapps and bookmarks.
The System Browser provides browser-like functionality where it is needed — including page navigation, search and bookmarks.
Gaia element are reusable UI components that presents Firefox OS look and feel.
BuildingBlock and Gaia Components
BuildingBlock is the reusable UI components set that presents Firefox OS look and feel. It’s being replaced by Gaia elements.
From 2.1, the BuildingBlock is progressively replaced by gaia-components, which use web component to make UI components more reusable. You can preview available components at http://gaia-components.github.io/gaia-components/ .
If you want to preview the Gaia components on desktop, you could browse to ‘about:config’ in Firefox, search for ‘dom.webcomponents.enabled’ preference and set value to
true. Then the required
Document.registerElement API is enabled.
WebIDE (was App Manager)
The WebIDE and App Manager is the development tool in Firefox for Desktop to help you test, deploy and debug HTML5 web apps on Firefox OS phones and the Firefox OS Simulator, directly from your browser.
The communications apps include Dialer, Contact, Messages, Emergency Call, Cost Control and FTU. Some telephony related functionality such as Cell Broadcast, Voice Mail are also in this scope.
Email, Calendar, Clock apps are in the productivity category.
The media apps consist of Camera, Gallery, Music, Video, FM Radio, Ringtones, and some media related functions such as forward lock DRM(fl) and wallpapers.
In addition to these functions, there are several major features such as Marketplace, test framework, pdf.js, which are developed closely internally or externally from Gaia.
Mozilla has been working actively to expose web capability to mobile devices. It’s done by defining web native APIs that make use of mobile sensors, telephony, wifi, batteries and so on.
Note that these APIs not only are designed make Firefox OS work, but also are proposed to become standards for all web browsers. When implemented on a conforming browser, these APIs can be used immediately and Web developers don’t need to ‘port’ their webapp to other platform or browser.
1.6 Permission and security model
Some WebAPIs are ready for use in FirefoxOS and Firefox for Android. Since some are essential to provide a full ‘smartphone’ experience, such as telephony, but the the development of the APIs is not finalized yet, some of those APIs can only be used by gaia and build-in apps. Those are called ‘certified’ API. Some APIs, such as TCP socket, are useful in some circumstances but may have security concerns. Webapp using those APIs need to be reviewed and signed by Firefox Marketplace or some other trusted organization to make sure the user won’t be offended. These APIs are called ‘privileged’ APIs.
In MDN WebAPI page shows ‘certified’ and ‘privileged’ tags after each WebAPI. Generally if you are a webapp developer, you can’t access to ‘certified’ APIs at this moment.
Here is the list of permissions that available.
1.7 Release Cycle
Since Firefox OS 1.2, Mozilla tries to align the Firefox OS release cycles with that of the Firefox desktop version (that is, 6 weeks). Firefox OS releases a new version every 3 months. So every Firefox OS release will bypass a Gecko (Firefox browser core) release.
For example. Firefox 1.4 is bundled with Gecko 30 and Firefox 2.0 is bundled with Gecko 32, which skips Gecko 31.
Check https://wiki.mozilla.org/RapidRelease/Calendar for the Firefox OS versions and the correspondent gecko versions.
1.8 Where to discuss and get reference
You can use irc://irc.mozilla.org #gaia to discuss with other gaia developers instantly. And feel free to find answers and ask/reply questions on StackOverflow with the tag ‘firefox-os’.
dev-gaia is the official mailing list of Gaia Development. Once you act as a gaia developer, you can learn a lot and participate in to change the world of web.
Please keep the article How To Ask Questions The Smart Way in mind before you start asking any question there.
1.9 Build the entire Firefox OS from source code
This book is about Firefox OS application layer: Gaia. We’ll just sketch the process of building the entire Firefox OS from source code.
Here’s a good evaluation choice called foxbox that helps you create a configured VM environment without affecting your desktop environment (disclosure: this tool is developed by the author). Your desktop should have hardware virtualization(VT-x or AMD-V) support. It’s available on Mac/Windows 8. Prepare to have on your workstation at least 4GB RAM and about 40GB disk space (for full OS, 5~10GB for gaia).
Generally you can config the target device with the following command:
Once your environment is settled down, command
config.sh <target> can help you config your build environment for the target device.
build.sh helps you build the device image, and
flash.sh flashes the ROM on to the device.
Firefox OS reuses the AOSP(Android Open Source Project) build system but does not build the java related parts. Instead of
lunch in android, Firefox OS wrap them in
The java related parts are build with
fake-jdk-tools folder. So Firefox OS developer do not have to modify much of AOSP build process.
You can read gonk-misc, build Firefox OS through AOSP build system (written in Chinese, you may use web translation tool to read it if you don’t read Chinese) to gain more detail about the Firefox OS build process.
1.10 Get a reference phone
FirefoxOS Reference Phone (Flame) is available with global free shipping for $170. It has 4 inch screen, and the RAM is configurable from 256MB to 1GB in the bootloader. This enables you to use same device to check your webapp with limited or rich memory.
I’d recommand you to get one for FirefoxOS development.
1.10.1 Flash the device
There’s a tool that help developers grab nightly builds and flash to the reference phone
You can check B2G-flash-tool for more detail.
- Public UI Spec https://mozilla.app.box.com/s/44utizl9oz4eupyu3fuu
Chapter 2 - Get in touch with Gaia
2.1 How to try Gaia
Firefox WebIDE is a developer tool available in Firefox for Desktop. It provides a number of useful tools to help you test, deploy and debug HTML5 web apps on Firefox OS phones and the Firefox OS Simulator, directly from your browser.
In desktop Firefox Browser 33+, open the WebIDE from MENU > Tools > Web Developer > WebIDE. Select a runtime from the menu and you are ready to experience Firefox OS.
The whole viewable and responsive things in the Simulator are done by Gaia.
2.2 How to get Gaia Source
It’s possible to only get Gaia source, run it with a nightly browser or simulator, and flash it without modifying Gecko. First, you need to have a Windows/Mac/Linux PC or laptop with
Click the ‘fork’ button in top right corner to fork to your own repository from https://github.com/mozilla-b2g/gaia. Now you can clone the code from your forked repository:
And remember to run the following command in that folder:
to add remote
upstream to your git remote repository.
2.2.1 How to keep gaia up to date
Once you have
mozilla-b2g/gaia in your git remote repository, you can run the command
to update all remote repository.
Then run the command
to make your local file up to date.
2.3 Run Gaia via Firefox mulet
Get and install the Firefox nightly version (codenane: mulet) from http://ftp.mozilla.org/pub/mozilla.org/b2g/nightly/latest-mozilla-central/.
The file is named like
Then execute the following commands in the gaia directory:
It will bring up a new firefox nightly window, with a Firefox OS frame in it.
Gaia provides a desktop-helper addon, which has a mockup of the Firefox OS device environment and provides some useful tools. The addon allows us to test and debug Gaia code in the browser and reuse all web tools.
2.4 How to install Gaia on a real device
Make sure your device is rooted. Then, you have to enable the remote debug console before installing Gaia on the device.
2.4.1 Enable the remote debug console
Firefox OS reuses the Hardware Abstraction Layer (HAL) of Android Open Source project (AOSP) and accordingly inherits some low-level debug tools from AOSP, such as
adb (Android Debug Bridge).
To install Gaia on a real device, you need to have
adb tool installed.
adb is a command line tool that lets you communicate with the device.
On your device, check
settings > Device Information > More information > Developer Menu. Then go back to top level of settings, and you’ll see the developer panel. Click it, then select the
Remote Debugging option as
ADB and Devtools.
It will enable the remote debug console and enable you to debug your device with the App manager.
2.4.2 Setup adb
WebIDE already wraps the adb helper addon
for Gaia developers. Connect your device via USB, and then tap
connect button in WebIDE to connect with your device.
If you like to use adb via command line, you can install adb manually.
Open http://developer.android.com/sdk/index.html, click
DOWNLOAD FOR OTHER PLATFORMS and download SDK Tools only for your platform.
Unzip it in your path and You can find the adb tool in
To make it work with Gaia build tools, edit PATH environment in windows,
~/.bash_profile in mac OS X, or the correspondent files in Linux distributions.
Let’s take OS X for example, edit ~/.bash_profile:
Save and reload the environment. Then, you can type ‘adb’ in command line to test if it works.
Once adb is settled, you can install Gaia into a real device.
2.4.3 Install Gaia on a real device
First, connect your device to your computer with a USB cable.
To check if there is any connected device, you can type:
If there’s a device attached, you can proceed with the running following commands. If you see no connected device with the above command, you (Windows or Linux distributions user) may need to check OEM USB Drivers page to correctly set up the USB driver on your computer.
Run the following command to reset your phone with your gaia source code
In 2.2 or above, we can add an extra parameter
P=1 to enable multiprocess compiling.
It will be way faster.
Install apps without reboot
To test non-system apps, you can install them without rebooting the device. Just run the command:
Install a specific app within Gaia
If you want to install a specific app only, you can pass it through the APP variable:
2.5 Debug with a real device
You still need the APP manager or adb tool to remote debug the apps on a Firefox OS Device.
Firefox OS shares the same console.log() command as normal web pages do. You can see the same log as in the Firefox Web Console
To clean up the log entries
To show the Error log entries only:
or filter with -s option to achieve the same output result:
The full adb tools usage is available on Android Debug Bridge page. Note that some android specific command may not work on Firefox OS devices.
2.6 Gaia source structure
Here’s the quick overview of the code structure and functionality.
All main Gaia apps, including the apps shown in homescreen, such as calendar, camera, and fundamental apps such as system, homescreen, and keyboard
Contains build scripts
dogfood_apps/, external-apps/, showcase_apps/, test_apps/
Folders containing other apps that will be included in customization.
marketplace is located in
external-apps. It’s developed separately and is included as a packaged app.
Keyboard dictionaries and layouts for different languages.
Localization files for different languages.
Files that are shared over the Gaia and will be included in build time
Tools for build script and test.
2.7 How a WebApp gets started
Once the system app tries to launch a built-in web app, it will try to open the
manifest://[app name].gaiamobile.org:8080 URL.
Gecko will try to parse the
manifest.webapp within a webapp.
manifest.webapp defines the launch path, and by convention it’s
index.html for all build-in webapps. The
You can refer to the manifest format from MDN.
[app name].js or
All app related styles are located in the
App-related language/localization strings are located in the
The localization is done with
shared/js/l10n.js, which wraps the
navigator.mozl10n API and changes the strings to the translated versions in the locales/*.properties files.
A general string will be
data-l10n-id attribute specifies a key which maps to a value inside of a properties file. This content is changed after the page loads.
You can refer to Localizing Firefox OS Apps for more detail.
The official translations are maintained separately in https://hg.mozilla.org/gaia-l10n.
App-related test cases are located within the
Check Chapter 4 for more about running tests.
2.8 How to contribute to Gaia
Gaia is an Open Source project. You can help this project with a variety of skills you’d like to perform such as documentation, testing, coding, marketing and so forth.
If you are not sure if Gaia is the project you’d like to work on, it’s ok. There’re plenty of Mozilla related projects that can help you do good with other people. Consult the What can I do wizard first.
2.8.1 Find a bug to contribute
If you expect to fix something in Gaia, check the Bugzilla to see if it has been done before you actually do it.
Mozilla uses the Bugzilla issue tracking system to track issues and bugs. It’s an essential tool to manage large-scale projects.
Bugzilla is the single place to track all Mozilla-related bugs, including Firefox OS/Gaia bugs
You can check the good first bug list, which are picked by experienced Mozilla developers. They are willing to mentor and help you fix some first easy bugs, to get familiar with the developing environment and how to contribute to these open source projects.
2.8.2 File a bug
The best ways to get contributing to an Open Source project is to file a bug.
Filing a bug allowing you to tell people that something is broken or a new thing you would like the project to do. It also introduces yourself to the existing community.
In the guide of writing a good bug, bugs can be categorized into two categories:
- Reporting errors
- Asking for new features or enhancements
There’s a specific https://developer.mozilla.org/en-US/Firefox_OS/Developing_Firefox_OS/Filing_bugs_against_Firefox_OS that shows how to file a Firefox OS bug.
Talk more on IRC & bugzilla to update your findings and how to analyze the issue.
Once you are committed to contribute to the Gaia project, there’re addon tools featuring github integration:
2.8.3 Submit a Pull Request for review
Once you have taken a bug and have a working fix in your own branch, you could submit a Pull Request for review.
To properly get the commit reviewed, please use ‘Add an attachment’ and paste your Pull Request on file field. Then set review or feedback flag to the proper module owner.
If you have worked on your branch for a while, you may need to rebase your branch and check the recent update did not conflict with your changes.
Run the commands:
to make your local file up to date and keep your commits above recent Gaia changes.
2.8.4 Use Git rebase to squish commits into one commit
The reviewer or feedbacker may give you some suggestions. Once you finish the change and commit again into your code base, please squish your commits into single commit. Therefore the commit log can have more clear while the Pull Request is merged.
Here is the reference about how to squish commit via git rebase command: http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html
2.8.5 Modify existing commit log
Commit logs are a general reference when people try to glance the App changelog to find out what’s happen with recent build. So a meaningful commit log is essential for a healthy open source project. Rather than just copy the Bugzilla issue statement, it’s more helpful to put
what problem you really solved,
what you have done in this patch into your commit log.
You can change your existing commit’s log via following command:
- Gaia Development Cycle
- Different ways to run Gaia (https://developer.mozilla.org/en-US/Firefox_OS/Developing_Gaia/Different_ways_to_run_Gaia)
- Developing Gaia
Chapter 3 - Gaia under the hood
3.1 Booting path
Before looking Gaia from above, we can take some time to know how we get to Gaia when we power on a device.
Gaia is launched from Gecko. On a Firefox OS device, Gecko is booting from the linux kernel. The Architecture overview on Mozilla Developer Network (MDN) describes the bootstrapping process of how FirefoxOS boots to Gecko.
The bootloader brings up the Firefox OS device, performs basic hardware checks and then hands off to the Linux Kernel to bring up the devices and run essential processes.
3.1.2 Linux Kernel process
The Linux Kernel used for Firefox OS is based on Android Open Source Project (AOSP). You can reference Android boot process to understand how to bring the device up to kernel.
The kernel will execute processes defined in
init.rc and the successor init.b2g.rc to launch essential process such as
b2g (the main FirefoxOS process, containing Gecko),
rild (telephony daemon process that might contain proprietary functionalities specific to the chipset).
After the processes in init.rc are launched, we successfully boot to Gecko (the
3.1.3 In b2g process (Gecko)
b2g process runs
libxul, which reference to
b2g/chrome/app/b2g.js to get the default preferences.
From the preferences it will open the described html file called
which is packed in the
The shell.html includes
b2g/chrome/content/shell.js file, which will trigger the Gaia
3.2 Search and Reference Gecko code
To search the Gecko code, you can use http://dxr.mozilla.org. It’s neat and provides good cross-reference features, but is resreicted a limited set of repositories. Other than that, you can try http://mxr.mozilla.org, which is less fancy than the MXR, but contains more Mozilla projects.
3.3 Gecko files that are related to Gaia
The following folders contains files that are relevant to gaia
The b2g folder contains mainly FirefoxOS related functions.
The entry point, the first html to load in gecko to launch the Gaia system app.
settings.js contains system default setting parameters.
shell.js is the first script to load the Gaia
shell.js imports all required modules, registers key listeners, defines
sendChromeEvent to communicate with Gaia, and provides webapp install helper. It also contains miscellaneous functions including indexedDB quota, RemoteDebugger, keyboard
helper, screenshot, etc. Among them, the most important one is that
system app and then hands over the overall system related
management work to the Gaia
Predefined references, like
about:config in the Firefox browser, same as Gaia
pref.js. Some preference values can be changed in the settings app. It can be overridden by Gaia’s user.js in Gaia build script.
Web API implementation are placed under the dom/ directory. Some older APIs are located in dom/base, ex navigator.cpp
Contains DOM APIs related to web apps, including permissions, installation, etc.
All Web app permissions are defined in PermissionsTable.jsm
Contains Web API definition files. Consult MDN WebIDL_bindings for supported attributes.
The hardware abstraction layer in Gecko interfacing with Gonk.
3.4 Generated files
Contains all configs.
3.5 Contribute to Gecko bug
Though this books focuses on Gaia, you can refer to How to submit a patch if you are interested and have a chance to patch gecko code.
Before that, you are also required to become a mozilla committer.
- FirefoxOS and its use of linux http://www.slideshare.net/aimeemaree/firefoxos-and-its-use-of-linux-a-deep-dive-into-gonk-architecture
Chapter 4 - Build Script
Gaia Building Script contains many helper tools to help install, test, localize, and package webapps onto a real device. It also allows developer to customize Gaia, like changing default wallpaper, ringtone, apps, settings, for different markets.
4.1 The build process
The Gaia build system performs multiple steps whhen you run a mere
make command in the Gaia folder.
First, the shell will download
xpcshell and extract it into your environment.
xpcshell functions are wrapped in a commonjs-like API in
build/xpcshell-common.js for developers to get hands on more easily. Check
build/test for more detail.
The following diagram provides an overview of the Gaia build process:
In earlier realease of Gaia, the build script handle each Gaia app’s custom build process. The build script will process the Gaia app from their source folder, place the output to the profile folder, and leave intermediate files under source folder.
From 2.1 on, app specific build processes are moved to separate
apps/<app>/build/build.js files. The build process now simplified to three stages:
Now intermediate files are processed from source folder to
stage folder, and then the final results are copied to the
Generates the default settings for FirefoxOS. It will generate
user.js and put onto the device to be read by Gecko.
Generates the default settings for FirefoxOS. It will be read by Gaia.
Files in the
shared/ folder that are declared in built-in webapp’s html will be included in this step.
Zips apps and puts them under the
From 2.1 on, per app build script are introduced. If
build.js is found in per app’s
build/ folder, it will take the responsibility of building this app instead of center
Also there are several parts that are handled by build script. You can refer to Build System Primer for more information.
4.2 Per-commit coding style check
jshint to check JS coding styles before each commit (done by git pre-commit hook). Once you submit a Pull Request to the Gaia repository, the TBPL server (Mozilla’s continue integration server) will run these linters to check that all styles are correctly followed.
The precommit hook script is in
tools/pre-commit and will be copied to project
.git/hooks folder once a make command is executed.
Install gjslint and jshint separately to check coding styles by your own.
jshint code quality check has been introduced in Gaia from 1.4 to complement with gjslint, the code style check tool. gjslint is planned to be replaced by jscs.
You can install it via npm:
You can check
build/jshint for more detail about jshint in Gaia.
Gaia also provide the build target for you. You can run
to automatically run gjslint and jshint style checks.
to run jshint style checks.
The build system provides tools to set up a variety of tests, including unit test, integration test, performance test, and UI test.
4.3.1 Unit Test
You can run the following command to host a unittest server:
Then open the test-agent app in nightly:
pwd shortcut in *nix system:
Then run all tests with the following command
You can add argument
APP=<app folder name> (such as
APP=settings) to test a single app.
4.3.2 Integration test with marionette js
You can run the following command to trigger the integration test:
Again, you can also append
APP=<app folder name> to test a single app, such as
After running the
test-integration command, you can load the profile to b2g with:
And with the
The developer can see the log on console.
If you’ve run
test-integration once, you can use the
test-integration-test command next time since
test-integration-test command won’t build the profile every time.
You can use a real device (like flame) to run the marionette test.
4.3.3 performance test
For Gaia performance test with Raptor, it’s only meaningful if you run the test on a real device.
You can install it independently via
$ npm install -g @mozilla/raptor
The performance test will boot up the device and launch the app several times to get an average app load time. Memory usages of both the app and the system process (b2g) are also collected and reported after the test completes.
You can append
APP=<app folder name> to test a single app, such as
APP=music. And append
RUNS=<number> for test rounds.
The test result may looks like below:
Mean denotes the average app load time, which should be less than 1 second for better user experience.
The golden rule for
raptor is that smaller numbers are better. We won’t mention too much about the detail of what this memory usage indicates, but just come with a simple note here:
- uss = unique set size
- pss = proportional set size
- rss = resident set size
Generally rss >= pss >= uss .
rss don’t accurately reflect a process’s usage of pages shared with other processes. So the two numbers you want to watch are the
uss. You can find more detailed descriptions of them online.
uss is the memory that is completely unique to that process. This is the amount of memory that would be freed if the application was terminated right now. It’s a key value for evaluation.
pss reports the proportional size of its shared libraries. It includes memory that is not released if the process was terminated.
make raptor, another alternative for performance test is b2g-perf.
To run it, first flash Gaia to the device with production configuration:
After the device boots up, run the
The result will look like:
mean:1664 denotes on this device the current average load time of the settings app is 1664ms.
More details underneath
Firefox OS App launch performance can be found in this talk
4.4 API document
Gaia doc uses the jsdoc3 format.
You can run the following command to generate Gaia docs:
Gaia supports customization for your own need, such as changing default wallpaper, ringtone, apps, settings.
You can specify the location with the GAIA_DISTRIBUTION_DIR environment variable, like this:
Read Customization Guide for more information.
4.6 Device type
Gaia contains some built-in device type distribution such as phone, tablet, or TV. Run the command:
to load default tablet-related settings and configurations.
The real operation is done by per app build script, which is located in
apps/<app name>/build folder.
4.7 Keyboard IME
To get keyboard IME layout and dictionary enabled, use the following command:
You have to download locale files separately. Take Traditional Chinese for example, you can get the locale file via mercurial(hg):
Run the command for to build:
The locale files should be listed in the languages_mine.json file.
The file can be as simple as
Refer to this gist for locale build automation script.
4.8.1 test localization via pseudolocales
You can enable pseudo-localization in your device’s developer panel. Then choose one of them in Settings->Languages (they’relocated at the very beginning of the list). After that you may test your patch. Every element that has l10n-enabled will look like mixed code.
There are some best practices about how to perform localization.
4.9 Beyond Build Script
There are helpful tools located in gaia/tools/ folder. Let’s take
png_recompress.sh for example.
Pick an image named ‘bg.png’ and run the command:
It will remove unnecessary metadata and further compress the png so that it may save up to 99.5% of size, which has a very measurable impact on ZIP file size and memory footprint.
4.9.2 Per commit tests via Treeherder
Million of Gaia builds are run via Treeherder. In addition to lint, unit-test, marionette js test, Gaia also runs buildscript test and gaia_ui_tests(marionette python version) on Treeherder.
4.9.3 Run Gaia ui test locally
If you see the
gaia_ui_tests error on Treeherder and want to reproduce it locally. You can refer to
tests/travis_ci/gaia_ui_tests/install to setup you local test environment:
The script enables standalone python virtual environment
virtualenv to run the tests so the related configurations won’t affect the entire host system. It fetches new b2g desktop version and then builds a desktop version of Gaia.
You can enter the following command to exit to normal console:
You can refer to MDN for more information about gaia UI test.