\n Preface\n
- \n Why I write this book\n
- \n Target Audience\n
- \n Credit\n
- \n Discussion\n
\n
\n Chapter 1 - Overview\n
- \n 1.1 Firefox OS architecture\n
- \n 1.2 Gecko Overview\n
- \n 1.3 Gonk Overview\n
- \n 1.4 Gaia Overview\n
- \n 1.5 WebAPI\n
- \n 1.6 Permission and security model\n
- \n 1.7 Release Cycle\n
- \n 1.8 Where to discuss and get reference\n
- \n 1.9 Build the entire Firefox OS from source code\n
- \n 1.10 Get a reference phone\n
- \n 1.10.1 Flash the device\n
- \n 1.11 Reference\n
\n
\n Chapter 2 - Get in touch with Gaia\n
- \n 2.1 How to try Gaia\n
- \n 2.2 How to get Gaia Source\n
- \n 2.3 Run Gaia via Firefox nightly\n
- \n 2.4 How to install Gaia on a real device\n
- \n 2.5 Debug with a real device\n
- \n 2.6 Gaia source structure\n
- \n 2.7 How a WebApp gets started\n
- \n 2.8 How to contribute to Gaia\n
- \n 2.9 Reference\n
\n
\n Chapter 3 - Gaia under the hood\n
- \n 3.1 Booting path\n
- \n 3.2 Search Gecko code\n
- \n 3.3 Gecko files that related to Gaia\n
- \n 3.4 Generated files\n
- \n 3.5 Contribute gecko related bug\n
- \n 3.6 Reference\n
\n
\n Chapter 4 - Build Script\n
- \n 4.1 The build process\n
- \n 4.2 Per commit Coding style check\n
- \n 4.3 Test\n
- \n 4.4 API document\n
- \n 4.5 Customization\n
- \n 4.6 Device type\n
- \n 4.7 Keyboard IME\n
- \n 4.8 Localization\n
- \n 4.8.1 test localization via pseudolocales\n
- \n 4.9 Beyond Build Script\n
\n

Preface

\n\n

Always bet on web

\n\n

1 \"You don't have to know if you bet on Web-based applications.\n2 No one can break that without breaking browsing.\n3 The Web may not be the only way to deliver software,\n4 but it's one that works now and will continue to work for a long time.\n5 Web-based applications are cheap to develop,\n6 and easy for even the smallest startup to deliver.\"\n7 -- Paul Graham on `why web applications are the other road ahead`. \n

\n\n

Firefox OS, the frontier of web technologies, is the voyage of \nthe Mozillans to explore strange new worlds, to seek out emerging and\n wild uninvented web technologies, and to boldly go where no man has been \nbefore!

\n\n

Firefox OS is the fantacy land. It shows that everything is achievable \nvia web technologies, and you, a web developer, can live with it happily \never after … oneday. The good thing is Firefox OS is open source: you \ncan be the one make it a reality!

\n\n

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.

\n\n

Since Firefox OS is evolving, this book is based on the master branch of Gaia (from v1.4 at 2014/12 to 2.2 2014/9).

\n\n

Why I write this book

\n\n

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.

\n\n

Target Audience

\n\n

Why bother reading this book

\n\n

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.

\n\n

Prerequisites

To make this book concise and readable, we assume readers to have background knowledge of Javascript, CSS, and HTML. \nHow to develop webapps is out of scope of this book as well. A reader can learn how to develop a Firefox OS webapp from reading the articles in Build Apps for Firefox OS, watching the videos series App Basics for Firefox OS, or reading the book Quick Guide For Firefox OS App Development.

\n\n

Let’s start the journey.

\n\n

Credit

\n\n

Thanks Mozilla to bring 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.

\n\n

The main author is Fred Lin who coordinates the book structure and the writing.

\n\n

Related chapters are based on presentations and documents from:

\n\n

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.

\n\n

Since the book is CC 2.0 shared-alike license, part of this book is available on MDN. Thanks Chris Mills for editing.

\n\n

Discussion

\n\n

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.

\n\n

Chapter 1 - Overview

\n\n

1.1 Firefox OS architecture

\n\n

The main Firefox OS architecture is

\n\n

Application Layer : known as \nGaia\n
Platform Layer : known as \nGecko\n
Infrastructure Layer : known as \nGonk\n

You may want to know the Firefox OS architecture better before you start\n developing Gaia. Here are introductory slides of of the Firefox OS and Gaia development flow: Developing Firefox OS and FirefoxOS for developers. Also there’s an Overview and High Level Architecture\n that elaborates the Firefox OS Architecture more concisely.

\n\n

Boot2Gecko (B2G)

\n\n

Boot2Gecko (B2G) is the project name of Firefox OS. You can see it anywhere through Firefox OS related projects. Firefox OS and Firefox are brand 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 simulator or the development build.

\n\n

\n $\"Simulator$

Simulator shows b2g os in Device section

\n\n

1.2 Gecko Overview

\n\n

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:

\n\n

1 Mozilla/5.0 (Windows NT 6.2; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) \\\n2 Chrome/32.0.1667.0 Safari/537.36\n

\n\n

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.

\n\n

Gecko supports web open standards: HTML, CSS, and JavaScript, and some experimental APIs to push web to the new frontier. Gecko also includes a networking stack, graphics stack, layout engine, a JavaScript virtual machine, and porting layers to makes sure those APIs work well on every operating system Gecko supports.

\n\n

You can download Gecko source by following the guide. (Note: To build full Firefox OS you don’t have to download gecko separately)

\n\n

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.

\n\n

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.

\n\n

1.3 Gonk Overview

\n\n

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.

\n\n

Gonk includes the Linux kernel, userspace hardware abstraction layer (HAL), and other OEM specific libraries.\nSince different devices may have their specific chipsets and varied hardware specs, the Gonk layer may look pretty different for devices.

\n\n

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.

\n\n

General gonk work includes porting to the specific board and make sure Gecko can work well on the device.

\n\n

1.4 Gaia Overview

\n\n

Gaia is the front-end of Firefox OS, which contains system \nadministration and build-in apps shipped with a Firefox OS device. \nAll gaia source, including the system, keyboard IMEs, and everything you can see \nare implemented with HTML5 (HTML+CSS+Javascript) & Open \nWebAPIs.

\n\n

The functionality of Gaia can be roughly categorized into the following groups:

\n\n

Platform

\n\n

Including System, Settings, Lockscreen, Build script, Keyboard and IME, and Bluetooth apps.

\n\n

\n $\"platform\"$

platform

\n\n

System

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.

\n\n

Window Management

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.

\n\n

Settings

\n\n

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.)

\n\n

Keyboard

\n\n

Keyboard is a special app which works closely with system. It handles layout and multiple input-method editors (IME).

\n\n

FrontEnd

\n\n

Homescreen

\n\n

Like other mobile platforms, Homescreen shows currently installed webapps and bookmarks.

\n\n

Browser

The System Browser provides browser-like functionality where it is needed — including page navigation, search and bookmarks.

\n\n

Gaia Elements

\n\n

Gaia element are reusable UI components that presents Firefox OS look and feel.

\n\n

BuildingBlock

\n\n

BuildingBlock is the reusable UI components set that presents Firefox OS look and feel. It’s being replaced by Gaia elements.

\n\n

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.

\n\n

Communications

\n\n

The communications apps include Dialer, Contact, SMS, Emergency Call, Cost Control and FTU.\nSome telephony related functionality such as Cell Broadcast, Voice Mail are also in this scope.

\n\n

\n $\"communications\"$

communications

\n\n

Productivity

\n\n

Email, Calendar, Clock apps are in the productivity category.

\n\n

\n $\"productivity\"$

productivity

\n\n

Media

\n\n

The media apps consist of Camera, Gallery, Music, Video, FM apps, Ringtones, and some media related functions such as forward lock DRM(fl) and wallpapers.

\n\n

\n $\"media\"$

media

\n\n

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.

\n\n

1.5 WebAPI

\n\n

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.

\n\n

The public APIs are documented on the MDN WebAPI page.\nSome APIs in progress are tracked in WebAPI proposed to W3C wiki page.

\n\n

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.

\n\n

1.6 Permission and security model

\n\n

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.

\n\n

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.

\n\n

Here is the list of permissions that available.

\n\n

1.7 Release Cycle

\n\n

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.

\n\n

For example. Firefox 1.4 is bundled with Gecko 30 and Firefox 2.0 is bundled with Gecko 32, which skips Gecko 31.

\n\n

Check https://wiki.mozilla.org/RapidRelease/Calendar for the Firefox OS versions and the correspondent gecko versions.

\n\n

1.8 Where to discuss and get reference

\n\n

The main resource of Gaia is available on Mozilla Developer Network and Mozilla Wiki.\nThe secondary source is in Mozilla Wiki. Or you can find some cutting edge features from Bugzilla.

\n\n

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’.

\n\n

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.

\n\n

Please keep the article How To Ask Questions The Smart Way in mind before you start asking any question there.

\n\n

1.9 Build the entire Firefox OS from source code

\n\n

This book is about Firefox OS application layer: Gaia. We’ll just sketch the process of building the entire Firefox OS from source code.

\n\n

Follow the instructions from build prerequisites, \nfetch code in Mozilla Developer Network to download the full Firefox OS source code.

\n\n

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).

\n\n

Remember to backup the phone system partition before the first time you try to flash your device.\nThen you are ready to follow build\n instructions to configure and flash the device or B2G simulator.

\n\n

Generally you can config the target device with the following command:

\n\n

1 ANDROIDFS_DIR=<absolute path to parent dir of system dir> ./config.sh <target>\n

\n\n

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.

\n\n

Firefox OS reuses the AOSP(Android Open Source Project) build system but does not build the java related parts. Instead of build/envsetup.sh and lunch in android, Firefox OS wrap them in config.sh.

\n\n

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.

\n\n

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.

\n\n

1.10 Get a reference phone

\n\n

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.

\n\n

I’d recommand you to get one for FirefoxOS development.

\n\n

1.10.1 Flash the device

\n\n

There’s a tool that help developers grab nightly builds and flash to the reference phone

\n\n

You can check B2G-flash-tool for more detail.

\n\n

1.11 Reference

\n\n

Public UI Spec https://mozilla.app.box.com/s/44utizl9oz4eupyu3fuu

Chapter 2 - Get in touch with Gaia

\n\n

2.1 How to try Gaia

\n\n

The quickest way to try Gaia is via Firefox WebIDE (for Firefox 33 above) or Firefox App Manager.

\n\n

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.

\n\n

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.

\n\n

The whole viewable and responsive things in the Simulator are done by Gaia.

\n\n

2.2 How to get Gaia Source

\n\n

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 git installed.

\n\n

You should fork the main Gaia repository to your own. It’s better to register a github account so you can contribute your code \nback to gaia and keep code in a maintainable way.

\n\n

Click the ‘fork’ button in top right corner to fork to your own repository from https://github.com/mozilla-b2g/gaia.\nNow you can clone the code from your forked repository:

\n\n

1 $ git clone https://github.com/gasolin/gaia.git\n

\n\n

And remember to run the following command in that folder:

\n\n

1 $ git remote add upstream https://github.com/mozilla-b2g/gaia.git\n

\n\n

to add remote mozilla-b2g/gaia as upstream to your git remote repository.

\n\n

2.2.1 How to keep gaia up to date

\n\n

Once you have mozilla-b2g/gaia in your git remote repository, you can run the command

\n\n

1 $ git remote update\n

\n\n

to update all remote repository.

\n\n

Then run the command

\n\n

1 $ git merge upstream/master\n

\n\n

to make your local file up to date.

\n\n

2.3 Run Gaia via Firefox nightly

\n\n

Get and install the Firefox nightly version (codenane: mulet) from http://ftp.mozilla.org/pub/mozilla.org/b2g/nightly/latest-mozilla-central/.\nThe file is named like firefox-xxx.en-US.mac64.dmg.

\n\n

Then execute the following commands in the gaia directory:

\n\n

1 $ DEBUG=1 make\n2 $ [app path]/firefox -profile [gaia absolute path]/profile-debug\n

\n\n

It will bring up a new firefox nightly window, with a Firefox OS frame in it.

\n\n

Gaia provides a desktop-helper addon, which has a mockup of the Firefox OS
\ndevice environment and provides some useful tools.\nThe addon allows us to test and debug Gaia code in the browser and reuse all web tools.

\n\n

2.4 How to install Gaia on a real device

\n\n

Make sure your device is rooted. Then you have to enable the remote debug console before installing gaia on the device.

\n\n

2.4.1 Enable the remote debug console

\n\n

Firefox OS reuses the Hardware Abstraction Layer (HAL) of Android Open \nSource project (AOSP) and accordingly inherits some low-level debug tools from AOSP, such as adb (Android Debug Bridge).

\n\n

To install gaia on a real device, you need have adb tool installed. adb is a command line tool that lets you communicate with the device.

\n\n

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.\nIt will enable the remote debug console and enable you to debug your device with the App manager.

\n\n

2.4.2 Setup adb

\n\n

WebIDE already wraps the adb helper \naddon\n for gaia developers. Connect your device via USB, and then tap connect button in WebIDE to connect with your device.

\n\n

If you like to use adb via command line, you can install adb manually.\nOpen http://developer.android.com/sdk/index.html, click DOWNLOAD FOR OTHER PLATFORMS and download SDK Tools only for your platform. \nUnzip it in your path and You can find the adb tool in <sdk>/platform-tools/.

\n\n

To make it work with gaia build tools, edit PATH environment in windows,\n edit ~/.bash_profile in mac OS X, or the correspondent file in Linux distributions.

\n\n

Let’s take OS X for example, edit ~/.bash_profile:

\n\n

1 export PATH=${PATH}:<absolute sdk path>/platform-tools\n

\n\n

Save and reload the environment. Then you can type ‘adb’ in command line to test if it works.

\n\n

Once adb is settled, you can install gaia into a real device.

\n\n

2.4.3 Install Gaia on a real device

\n\n

First connect your device to your computer with a USB cable.

\n\n

To check if there is any connected device, you can type:

\n\n

1 $ adb devices\n2 List of devices attached \n3 emulator-5554  device\n

\n\n

If there’s a device attached, you can proceed with the running following commands.\nIf 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.

\n\n

Clean Install

\n\n

Run the following command to reset your phone with your gaia source code

\n\n

1 $ make reset-gaia\n

\n\n

In 2.2 or above, we can add an extra parameter P=1 to enable multiprocess compiling.

\n\n

1 $ make reset-gaia P=1\n

\n\n

It will be way faster.

\n\n

Install apps without reboot

\n\n

To test non-system apps, you can install them without rebooting the device.\nJust run the command

\n\n

1 $ make install-gaia\n

\n\n

Install a specific app within gaia

\n\n

If you want to install a specific app only, you can pass it through the APP \nvariable:

\n\n

1 $ make install-gaia APP=browser\n

\n\n

2.5 Debug with a real device

\n\n

You still need the APP manager or adb tool to remote debug the apps on a Firefox OS Device.

\n\n

Firefox OS share the same console.log() command as normal web pages do. You can see the same log as in the Firefox Web Console

\n\n

1 $ adb logcat\n

\n\n

To clean up the log entries

\n\n

1 $ adb logcat -c\n

\n\n

To show the Error log entries only:

\n\n

1 $ adb logcat | grep \"Error\"\n

\n\n

or filter with -s option to achieve the same output result

\n\n

1 $ adb logcat -s \"Error\"\n

\n\n

The full adb tools usage is available on \nAndroid Debug Bridge page.\nNote that some android specific command may not work on Firefox OS devices.

\n\n

2.6 Gaia source structure

\n\n

Here’s the quick overview of the code structure and functionality.

\n\n

apps/

\n\n

all main gaia apps, including the apps shown in homescreen, such as calendar, camera, and fundamental apps such as system, homescreen, and keyboard

\n\n

build/

\n\n

contains build scripts

\n\n

dogfood_apps/, external-apps/, showcase_apps/, test_apps/

\n\n

folders containing other apps that will be included in customization.

\n\n

Firefox marketplace is located in external-apps. It’s developed separately and is included as a packaged app.

\n\n

keyboard/

\n\n

keyboard dictionaries and layouts for different languages.

\n\n

locales/

\n\n

localization files for different languages.

\n\n

shared/

\n\n

Files that are shared over the Gaia and will be included in build time

\n\n

tools/

\n\n

tools for build script and test.

\n\n

2.7 How a WebApp gets started

\n\n

All build-in WebApps are packaged webapps, which are essentially zip files containing all application assets: HTML, CSS, JavaScript, images, manifest, etc.\nEach WebApp in gaia is organized with the following structure:

\n\n

1 apps/[app name]/\n2  - js\n3  - styles\n4  - locales\n5  - test\n6  - index.html\n7  - manifest.webapp\n

\n\n

\n $\"webapp$

webapp load process

\n\n

Once the system app tries to launch a built-in webapp, it will try to open the manifest://[app name].gaiamobile.org:8080 URL.\nGecko 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 index.html file will load the required styles and javascript.

\n\n

You can refer to the manifest format from MDN.

\n\n

2.7.1 js

\n\n

All javascripts are located in the /js folder.

\n\n

As an informal convention, the major javascript entrypoint will be named as [app name].js or main.js.

\n\n

2.7.2 styles

\n\n

All app related styles are located in the /styles folder.

\n\n

2.7.3 locales

\n\n

App-related language/localization strings are located in the /locales folder.

\n\n

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.

\n\n

A general string will be

\n\n

1 <span data-l10n-id=\"hello\">hello</span>\n

\n\n

The 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.

\n\n

You can refer to Localizing Firefox OS Apps for more detail.

\n\n

The official translations are maintained separately in https://hg.mozilla.org/gaia-l10n.

\n\n

2.7.4 tests

\n\n

App-related test cases are located within the /test folder.\nCheck Chapter 4 for more about running tests.

\n\n

2.8 How to contribute to Gaia

\n\n

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.

\n\n

If you are not sure if Gaia is the project you’d like to work on, it’s ok.\nThere’re plenty of Mozilla related projects that can help you do good with other people. \nConsult the What can i do wizard first.

\n\n

2.8.1 Find a bug to contribute

\n\n

If you expect to fix something in gaia, check the Bugzilla to see if it has been done before you actually do it.

\n\n

Mozilla uses the Bugzilla issue tracking \nsystem to track issues and bugs. It’s an essential tool to\nmanage large-scale projects.

\n\n

Bugzilla is the single place to track all Mozilla-related bugs, including Firefox OS/Gaia bugs

\n\n

Here’s a good reference of using bugzilla\nand a more tips and hacks of using bugzilla.

\n\n

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.

\n\n

2.8.2 File a bug

\n\n

The best ways to get contributing to an Open Source project is to file a bug.

\n\n

Filing a bug allowing you to tell \npeople that something is broken or a new thing you would like the \nproject to do. It also introduces yourself to the existing community.

\n\n

In the guide of writing a good \nbug, bugs can \nbe categorized into two categories:

\n\n

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.

\n\n

Talk more on IRC & bugzilla to update your findings and how to \nanalyze the issue.

\n\n

Once you are committed to contribute to the Gaia project, there’re addon \ntools featuring github integration:

\n\n

2.9 Reference

\n\n

Gaia Development Cycle
Different ways to run Gaia (https://developer.mozilla.org/en-US/Firefox_OS/Developing_Gaia/Different_ways_to_run_Gaia)

Chapter 3 - Gaia under the hood

\n\n

3.1 Booting path

\n\n

Before looks Gaia from above, we can take some time to know how we go to Gaia when we power-on a device.

\n\n

Gaia is booting from Gecko. On Firefox OS device, the Gecko is booting from linux kernel. The Architecture overview in Mozilla Developer Network (MDN) described the bootstrapping process of how FirefoxOS is booting to Gecko.

\n\n

\n $\"System$

System bootup flow

\n\n

3.1.1 Bootloader process

\n\n

Bootloader bring up the Firefox OS device, checking basic hardwares are functional, then Linux Kernel will take the responsibility to bring up devices and run essential processes.

\n\n

3.1.2 Linux Kernel process

\n\n

The Linux Kernel used for Firefox OS is based on Android Open Source Project (AOSP). You can reference Android boot process to understand howto bring the device up to kernal.

\n\n

kernel will execute processes defined in init.rc and the successor init.b2g.rc to boot essential process such as b2g (FirefoxOS basic process, containing Gecko), rild (telephony related process that might proprietary by different chipsets).

\n\n

Then we already boot to Gecko (the b2g process).

\n\n

3.1.3 In b2g process (Gecko)

\n\n

The b2g process runs libxul, which reference to b2g/chrome/app/b2g.js to get default preference.\nFrom the perference it will open the described html file called b2g/chrome/content/shell.html,\nwhich is compiled within the omni.ja file.\nThe shell.html includes b2g/chrome/content/shell.js file, which will trigger the Gaia system app.

\n\n

\n $\"FirefoxOS$

FirefoxOS structure

\n\n

3.2 Search Gecko code

\n\n

To search code in gecko, you could use \nhttp://dxr.mozilla.org. It’s more fancy and \nprovide good jump and reference features, but with limited repositories.\nOr you could try the traditional http://mxr.mozilla.org, which \ncontains more Mozilla projects.

\n\n\n\n

Following folders contains files that related to gaia

\n\n

b2g/

\n\n

b2g folder contains mainly FirefoxOS related functions.

\n\n

b2g/chrome/content

Contain Javascript files run above system app

\n\n

b2g/chrome/content/shell.html

The entry point, the first html to load Gaia system app.

\n\n

in shell.html, Gecko include settings.js and shell.js

\n\n

1 <script type=\"application/javascript;version=1.8\"\n2       src=\"chrome://browser/content/settings.js\"> </script>\n3 <script type=\"application/javascript;version=1.8\"\n4       src=\"chrome://browser/content/shell.js\"> </script>\n

\n\n

settings.js are system default setting parameters.

\n\n

b2g/chrome/content/shell.js

shell.js is the first script to load Gaia system app.

\n\n

shell.js import all required modules, register key listeners, \ndefined\n sendCustomEvent and sendChromeEvent to communicate with Gaia, and \nprovide webapp install helper. indexedDB quota, RemoteDebugger, keyboard\n helper, screenshot. But the most important thing is shell.js launch \nthe Gaia system app, then hand over the overall system related \nmanagement work to Gaia system app.

\n\n

1 let systemAppFrame =\n2   document.createElementNS('http://www.w3.org/1999/xhtml', 'html:iframe');\n3 ....\n4 container.appendChild(systemAppFrame);\n

\n\n

b2g/chrome/app/b2g.js

predefined references, like about:config in browser, same as gaia pref.js Can change this values in settings. Can be overwrite with Gaia’s user.js in Gaia build script.

\n\n

mozilla/central/dom/{API}

API implementation after b2g will locate in dom/. Older API will locate in dom/base, ex navigator.cpp

\n\n

mozilla/central/dom/apps

.jsm will be loaded. .js API implementation ex: webapp.js install, getSelf…

\n\n

mozilla/central/dom/apps/src/

PermissionsTable.jsm All permissions are defined in PermissionsTable.jsm

\n\n

mozilla/central/dom/webidl

language to define web api. search MDN WebIDL_bindings for supported attributes.

\n\n

mozilla/central/hal/gonk

hardware related gonk port layer.

\n\n

3.4 Generated files

\n\n

module/libpref/src/init/all.js

contain all configs

\n\n

/system/b2g/omni.ja the omni.js

contains the pack of styles, resources in device.

\n\n\n\n

Though this books is focus on gaia. You could refer How to submit a patch if you have a chance to patch gecko code.

\n\n

Before that, you also require to become a mozilla committer.

\n\n

3.6 Reference

\n\n

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

\n\n

Gaia did many tricks in build time. Build scripts are originally written in bash (Makefile), python, and javascript. After Firefox OS 1.4, build scripts are mostly written in Javascript and executed by xpcshell. xpcshell is similar to node.js but its possible to run some mozilla flavored javascript. It even allows core Gaia build script runs in a Firefox extension.

\n\n

Gaia Building Script contains many helper tools to help install, test, localization, and package webapp into real device. It also allows developer to customize gaia for different markets such as change default wallpaper, ringtone, apps, settings.

\n\n

4.1 The build process

\n\n

Gaia build process is constructed by multiple steps While you run make command in gaia folder.\nFirstly the shell will download xpcshell and extract it into your environment. The xpcshell api are wrapped to commonjs-like API via build/xpcshell-common.js so developer could pick it up easier. Check build/utils-xpc.js and build/test for the mapping details.

\n\n

The general build process looks like below.

\n\n

$\"Build$ credit

\n\n

For old days the build script handle each gaia app’s custom build process. Build script will process the gaia app from their source folder to profile folder, and leave intermediate files into source folder.

\n\n

From 2.1, app specific build process are moved to each apps/<app>/build/build.js files.\nThe build process now simplified to three processes: pre-app, in-app, and post-app processes.\nAnd now intermediate files will be processed from source folder to stage folder, then copy the final results into profile folder.

\n\n

\n $\"New$

New build process

\n\n

preference.js

\n\n

Generate the default settings for FirefoxOS. It will generate file user.js and put into the device, where is read by Gecko.

\n\n

settings.js

\n\n

Generate the default settings for FirefoxOS. It will be read by Gaia.

\n\n

webapp-shared.js

\n\n

Files in shared/ folder that declared in build-in webapp’s html will be included in this step.

\n\n

webapp-optimize.js

\n\n

minify app javascripts and l10n files.

\n\n

webapp-zip.js

\n\n

zip apps and put them under profile/.

\n\n

From 2.1, per app build script are introduced. If build.js is found in per app’s build/ folder, it will take responsibility of build this app instead of center app.js.

\n\n

And there are several parts that handled by build script. You can refer to Build System Primer for more information.

\n\n

4.2 Per commit Coding style check

\n\n

Gaia project follows Google javascript coding style.\n To ensure the style are the same, Gaia will use gjslint and jshint to check JS coding styles before each commit (done by git pre-commit hook). Once you submit a Pull Request to Gaia repository, the TBPL server (Mozilla’s continue integration server) will run these linters to double check all styles are correct.

\n\n

The precommit hook script is in tools/pre-commit and will be copied to project .git/hooks folder once some make command is executed.

\n\n

Install gjslint and jshint separately to check coding styles by your own.

\n\n

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.

\n\n

You can install it via npm:

\n\n

$ npm install -g jshint

\n\n

You could check build/jshint for more detail about jshint in gaia.

\n\n

But gaia also provide the build script for you. You could run

\n\n

$ make lint

\n\n

to automatically run gjslint and jshint style check.

\n\n

Or run

\n\n

$ make hint

\n\n

to run jshint style check.

\n\n

4.3 Test

\n\n

Buildscript provide tools to setup variety of test. including unit test, integration test, performance test, and UI test.

\n\n

4.3.1 Unit Test

\n\n

Gaia use mocha as test framework, chai as assert library, sinon.js as mock&stub library, blanket.js as test coverage tool.

\n\n

You could run following command to host a unittest server:

\n\n

$ make test-agent-server

\n\n

Then open the test-agent app in nightly

\n\n

$ make DEBUG=1\n $ [FirefoxNightly path]/firefox –profile [absolute path]/gaia/profile-debug http://test-agent.gaiamobile.org:8080

\n\n

or use pwd shortcut in *nix system:

\n\n

$ firefox -profile pwd/profile-debug http://test-agent.gaiamobile.org:8080

\n\n

Then run all tests with following command

\n\n

$ make test-agent-test

\n\n

You are able to append APP=<app folder name> to test single app, such as APP=settings.

\n\n

4.3.2 Integration test with marionette js

\n\n

Gaia Integration tests are driven by marionette script written by javascript and python.\nIt can communicate with gecko so it’s possible to control both browser and Firefox OS device and interact with each other.

\n\n

You could run following command to trigger the integration test:

\n\n

1 $ make test-integration\n

\n\n

You are able to append APP=<app folder name> to test single app, such as APP=calendar.

\n\n

\n $\"integration$

integration test result for calendar app

\n\n

After test-integration command, you could load profile to b2g via command:

\n\n

1 $ b2g/Contents/MacOS/b2g-bin -profile <absolute path>/gaia/profile-test\n

\n\n

With VERBOSE=1 option

\n\n

1 $ make test-integration VERBOSE=1\n

\n\n

developer could see the log on console.

\n\n

If you’ve runned test-integration once, you could use test-integration-test command in next time since test-integration-test command won’t build the profile everytime.

\n\n

You could use real device (like flame) to run marionette test.

\n\n

1 $ adb forward tcp:2828 tcp:2828\n2 $ MARIONETTE_RUNNER_HOST=marionette-device-host make test-integration\n

\n\n

4.3.3 performance test

\n\n

For Gaia performance test, it only meaningful if you run the test on real device.

\n\n

You’ll need an engineer build with Marionette enabled and remote debugging disabled.

\n\n

The performance test will trigger the device and launch app several times to get average app load time. After running a test, the performance also collect the memory usage of both the app and the system process (b2g).

\n\n

1 $ MARIONETTE_RUNNER_HOST=marionette-device-host make test-perf\n

\n\n

You are able to append APP=<app folder name> to test single app, such as APP=settings.

\n\n

1 \"mozPerfDurationsAverage\": 225.5\n

\n\n

mozPerfDurationsAverage is the average app load time, which should be less than 1 second to get better user experience.

\n\n

 1 {\n 2           \"app\": {\n 3             \"name\": \"Settings\",\n 4             \"uss\": 16.6,\n 5             \"pss\": 19.5,\n 6             \"rss\": 32.9,\n 7             \"vsize\": 73.3\n 8           },\n 9           \"system\": {\n10             \"name\": \"b2g\",\n11             \"uss\": 50.1,\n12             \"pss\": 53.2,\n13             \"rss\": 67,\n14             \"vsize\": 148.1\n15           }\n16 },\n

\n\n

The golden rule for test-perf is the lower number is better. We won’t mention too much about the detail of what these memory usage indicates. but just come with a simple note here:

\n\n

uss = unique set size
pss = proportional set size
rss = resident set size
vsize = virtual set size

Generally vsize >= rss >= pss >= uss . vsize and 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 pss and uss. You could google it for more detail.

\n\n

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.

\n\n

pss reports the proportional size of its shared libraries. This is memory that would not be released if the process was terminated.

\n\n

Besides make test-perf. Another option is b2g-perf.\nFirst flash gaia to device with production configuration:

\n\n

1 $ GAIA_OPTIMIZE=1 make production\n

\n\n

After the device bootup, run the b2g-perf command:

\n\n

1 $ pip install b2gperf\n2 $ adb forward tcp:2828 tcp:2828\n3 $ b2gperf --delay=10 Settings\n

\n\n

The result will be something like this

\n\n

1 2014-03-28 17:51:27,349 B2GPerfRunner INFO    | Results for Settings, cold_load_\\\n2 time: median:1658, mean:1664, std: 58, max:1931, min:1578, all:1665,1624,1687,16\\\n3 47,1628,1622,1654,1648,1663,1629,1619,1641,1664,1669,1578,1632,1705,1658,1725,16\\\n4 61,1623,1699,1653,1621,1682,1693,1680,1659,1668,1931\n

\n\n

The mean:1664 denotes in this device the current average load time of settings app is 1664ms.

\n\n

More details underneath Firefox OS App launch performance could be find in this talk

\n\n

4.4 API document

\n\n

Gaia doc adopt jsdoc3 format.

\n\n

You could run following command to generate docs:

\n\n

$ make docs

\n\n

4.5 Customization

\n\n

Gaia can do customization for you need. Such as change default wallpaper, ringtone, apps, settings.

\n\n

You can specify the location with the GAIA_DISTRIBUTION_DIR environment variable, like this:

\n\n

GAIA_DISTRIBUTION_DIR=<distribution_path> make production</distribution_path>

\n\n

Read Customization Guide for more reference.

\n\n

4.6 Device type

\n\n

Gaia contains some build-in device type distribution such as phone, tablet, or TV. Run command:

\n\n

1 GAIA_DEVICE_TYPE=tablet\n

\n\n

To load default tablet related settings and configurations.\nThe real operation is done by per app build script, which is located in apps/<app name>/build folder.

\n\n

4.7 Keyboard IME

\n\n

To get keyboard IME layout and dictionary enabled, use following command:

\n\n

$ GAIA_KEYBOARD_LAYOUTS=en,zh-Hant-Zhuyin,el,de,fr,zh-Hans-Pinyin make

\n\n

4.8 Localization

\n\n

You have to download locale files separately. Take traditional chinese for example, you can get the locale file via mercurial(hg):

\n\n

$ hg clone https://hg.mozilla.org/gaia-l10n/zh-TW/ B2G/gaia/locales/zh-TW

\n\n

Run command:

\n\n

$ LOCALE_BASEDIR=locales/ LOCALES_FILE=locales/languages_mine.json make

\n\n

Locale files should be listed in the languages_mine.json file.

\n\n

The file could be as simple as

\n\n

1 {\n2 \"en-US\" : \"English (US)\",\n3 \"zh-TW\" : \"正體中文 (繁體)\"\n4 }\n

\n\n

Referring to this gist for locale build automation script.

\n\n

4.8.1 test localization via pseudolocales

\n\n

You could enable Pseudo-localization in your device’s developer panel. , and then choose one of them in Settings->Languages (they’relocated at the very beginning of the list). Then test your patch. Every element that have l10n will be looks like mixed code.

\n\n

\n $\"pseudo$

pseudo locale

\n\n

There are some best practices about how to do localizations.

\n\n

4.9 Beyond Build Script

\n\n

4.9.1 Tools

\n\n

There are helpful tools located in gaia/tools/ folder . Let’s take png_recompress.sh for example.

\n\n

Pick an image named ‘bg.png’ and run command:

\n\n

1 $ ./tools/png_recompress.sh -v bg.png\n

\n\n

It will remove unnecessary metadata and further compress the png, so it could save up to 99.5% of size, which has a very measurable impact on ZIP file size and memory footprint.

\n\n

4.9.2 Travis tests

\n\n

Gaia project is hosted in github, and it use Travis CI to do per-commit continue integration and Pull request test.

\n\n

You can browse over 32000 builds are runned via Travis. Besides lint, unit-test, marionette js test. gaia also runs buildscript test and gaia_ui_tests(marionette python version) in Travis.

\n\n

To explore what exactly gaia tests runs in travis, check .travis.yml, which defined all travis tasks. The details of running scripts are defined in tests/travis_ci.

\n\n

If you see the gaia_ui_tests error on Travis and want to reproduce it locally. You could refer to tests/travis_ci/gaia_ui_tests/.

\n\n

Follow tests/travis_ci/gaia_ui_tests/install to setup test environment:

\n\n

1 $ virtualenv --no-site-packages ENV\n2 $ source ENV/bin/activate\n3 $ ROOT=$PWD\n4 $ cd tests/python/gaia-ui-tests/\n5 $ python setup.py develop\n6 $ cd $ROOT\n7 $ make b2g\n8 $ DESKTOP_SHIMS=1 NOFTU=1 make\n

\n\n

The script enable standalone python virtual environment virtualenv to run the tests so the related configurations won’t affect the entire host system. It fetched new b2g desktop version and build a desktop gaia version.

\n\n

Then run tests/travis_ci/gaia_ui_tests/script

\n\n

 1 $ export GAIATEST_ACKNOWLEDGED_RISKS=true\n 2 $ export GAIATEST_SKIP_WARNING=true\n 3 $ root=tests/python/gaia-ui-tests/gaiatest\n 4 $ b2g=`find b2g -follow -name \"b2g-bin\" | tail -n 1`\n 5 $ python $root/cli.py --app=b2gdesktop \\\n 6   --binary=$b2g \\\n 7   --profile=profile \\\n 8   --type=b2g \\\n 9   --timeout=10000 \\\n10   tests/python/gaia-ui-tests/gaiatest/tests/accessibility/lockscreen/test_a11y_u\\\n11 nlock_to_homescreen.py\n

\n\n

You could enter following command to exit to normal console:

\n\n

1 $ deactivate\n

\n\n

You could refer MDN for gaia ui test.

\n\n

Reference

\n\n

https://developer.mozilla.org/en-US/Firefox_OS/Platform/Gaia/Build_System_Primer
https://speakerdeck.com/yurenju/gaia-build-system-introduction

\n\n","tocStructure",[302,303,304,305,306,307,308,309,310,311,312,313,314,315,316,317,318,319,320,321,322,323,324,325,326,327,328,329,330,331,332,333,334,335,336,337,338,339,340,341,342,343,344,345,346,347],{"_134":135,"_43":136,"_129":-5,"_137":138,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":143,"_43":144,"_129":-5,"_137":145,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":143,"_43":150,"_129":-5,"_137":151,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":143,"_43":153,"_129":-5,"_137":154,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":143,"_43":156,"_129":-5,"_137":157,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":135,"_43":159,"_129":-5,"_137":160,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":143,"_43":163,"_129":-5,"_137":164,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":143,"_43":166,"_129":-5,"_137":167,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":143,"_43":169,"_129":-5,"_137":170,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":143,"_43":172,"_129":-5,"_137":173,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":143,"_43":175,"_129":-5,"_137":176,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":143,"_43":178,"_129":-5,"_137":179,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":143,"_43":181,"_129":-5,"_137":182,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":143,"_43":184,"_129":-5,"_137":185,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":143,"_43":187,"_129":-5,"_137":188,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":143,"_43":190,"_129":-5,"_137":191,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":143,"_43":193,"_129":-5,"_137":194,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":143,"_43":196,"_129":-5,"_137":197,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":135,"_43":199,"_129":-5,"_137":200,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":143,"_43":203,"_129":-5,"_137":204,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":143,"_43":206,"_129":-5,"_137":207,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":143,"_43":209,"_129":-5,"_137":210,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":143,"_43":212,"_129":-5,"_137":213,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":143,"_43":215,"_129":-5,"_137":216,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":143,"_43":218,"_129":-5,"_137":219,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":143,"_43":221,"_129":-5,"_137":222,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":143,"_43":224,"_129":-5,"_137":225,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":143,"_43":227,"_129":-5,"_137":228,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":135,"_43":230,"_129":-5,"_137":231,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":143,"_43":234,"_129":-5,"_137":235,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":143,"_43":237,"_129":-5,"_137":238,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":143,"_43":240,"_129":-5,"_137":241,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":143,"_43":243,"_129":-5,"_137":244,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":143,"_43":246,"_129":-5,"_137":247,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":143,"_43":249,"_129":-5,"_137":250,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":135,"_43":252,"_129":-5,"_137":253,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":143,"_43":256,"_129":-5,"_137":257,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":143,"_43":259,"_129":-5,"_137":260,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":143,"_43":262,"_129":-5,"_137":263,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":143,"_43":265,"_129":-5,"_137":266,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":143,"_43":268,"_129":-5,"_137":269,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":143,"_43":271,"_129":-5,"_137":272,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":143,"_43":274,"_129":-5,"_137":275,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":143,"_43":277,"_129":-5,"_137":278,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":143,"_43":280,"_129":-5,"_137":281,"_130":139,"_146":-5,"_147":-5,"_148":-5},{"_134":143,"_43":283,"_129":-5,"_137":284,"_130":139,"_146":-5,"_147":-5,"_148":-5},"publicChapterContent","nextChapter","sections",[],"routes/_store+/_layout","routes/_store+/_readers+/_layout","actionData","errors"]

Table of Contents

Preface

Why I write this book

Target Audience

Why bother reading this book

Prerequisites

Credit

Discussion

Chapter 1 - Overview

1.1 Firefox OS architecture

Boot2Gecko (B2G)

1.2 Gecko Overview

1.3 Gonk Overview

1.4 Gaia Overview

Platform

System

Window Management

Settings

Keyboard

FrontEnd

Homescreen

Browser

Gaia Elements

BuildingBlock

WebIDE (was App Manager)

Communications

Productivity

Media

1.5 WebAPI

1.6 Permission and security model

1.7 Release Cycle

1.8 Where to discuss and get reference

1.9 Build the entire Firefox OS from source code

1.10 Get a reference phone

1.10.1 Flash the device

1.11 Reference

Chapter 2 - Get in touch with Gaia

2.1 How to try Gaia

2.2 How to get Gaia Source

2.2.1 How to keep gaia up to date

2.3 Run Gaia via Firefox nightly

2.4 How to install Gaia on a real device

2.4.1 Enable the remote debug console

2.4.2 Setup adb

2.4.3 Install Gaia on a real device

Clean Install

Install apps without reboot

Install a specific app within gaia

2.5 Debug with a real device

2.6 Gaia source structure

apps/

build/

dogfood_apps/, external-apps/, showcase_apps/, test_apps/

keyboard/

locales/

shared/

tools/

2.7 How a WebApp gets started

2.7.1 js

2.7.2 styles

2.7.3 locales

2.7.4 tests

2.8 How to contribute to Gaia

2.8.1 Find a bug to contribute

2.8.2 File a bug

2.9 Reference

Chapter 3 - Gaia under the hood

3.1 Booting path

3.1.1 Bootloader process

3.1.2 Linux Kernel process

3.1.3 In b2g process (Gecko)

3.2 Search Gecko code

3.3 Gecko files that related to Gaia

b2g/

b2g/chrome/content

b2g/chrome/content/shell.html

b2g/chrome/content/shell.js

b2g/chrome/app/b2g.js

mozilla/central/dom/{API}

mozilla/central/dom/apps