Gaia/Hacking: Difference between revisions

Revision as of 15:01, 5 December 2012

Note: This page is soon migrating to MDN. Please contribute your changes there.

Gaia is the collection of web apps which make up the front end of Firefox OS (codenamed Boot to Gecko).

Everything you see on the screen in Firefox OS is built using open web technologies, including the homescreen and dialer.

You can get started hacking on Gaia with nothing more than a web browser and a text editor, so what are you waiting for?

Running Gaia Apps

There are two ways to run Gaia apps:

B2G Desktop
B2G on a device

B2G Desktop

B2G Desktop is a desktop build of the B2G app runtime used on devices where all apps should run as they would on a device, including the homesreen.

Aurora Builds (v1 everyone should use this)

You can download an Aurora build of B2G Desktop from http://ftp.mozilla.org/pub/mozilla.org/b2g/nightly/latest-mozilla-aurora/ for Linux, OS X and Windows.

Aurora/Nightly builds include gaia by default, and they should just run out of the box. This is done by using a wrapper program. When a profile is bundled with the nightly build (GAIADIR specified in the mozconfig), the binary 'b2g' is a wrapper program and 'b2g-bin' is the actual b2g binary.

If you want to modify Gaia, you will need to separately clone and "build" Gaia:

$ git clone git://github.com/mozilla-b2g/gaia.git gaia
$ cd gaia
$ DEBUG=1 make

Then you just run with B2G Desktop instead of Firefox. The nightlies produced for TBPL use 'b2g-bin'. If you build a desktop build yourself without specifying "GAIADIR=/path/to/gaia/repo" in your mozconfig, use 'b2g':

$ /path/to/b2g-bin -profile /path/to/gaia/profile

On OSX, the b2g-bin will be in the B2G.app package contents, so the path is a little different:

$ /path/to/b2g/B2G.app/Contents/MacOS/b2g-bin -profile /path/to/gaia/profile

To update gaia you run the following command inside the Gaia directory:

$ git pull

(or "git fetch && git merge upstream/master" if you checked out from your own clone).

Gaia Version 2

Use the below builds for work on version 2 of Gaia.

You can download a nightly build of B2G Desktop from http://ftp.mozilla.org/pub/mozilla.org/b2g/nightly/latest-mozilla-central/ for Linux, OS X and Windows.

Build Your Own

If you prefer you can build B2G Desktop yourself by checking it out from mozilla-central using Mercurial:

$ hg clone http://hg.mozilla.org/mozilla-central src

Before building, make sure you have the correct build prerequisites to build mozilla-central for your platform. After that, create a file called .mozconfig in your source tree to configure some options. Here's an example:

mk_add_options MOZ_OBJDIR=../build
mk_add_options MOZ_MAKE_FLAGS="-j9 -s"

ac_add_options --enable-application=b2g
ac_add_options --disable-libjpeg-turbo
 
# This option is required if you want to be able to run Gaia's tests
ac_add_options --enable-tests

# turn on mozTelephony/mozSms interfaces
# Only turn this line on if you actually have a dev phone
# you want to forward to. If you get crashes at startup,
# make sure this line is commented.
#ac_add_options --enable-b2g-ril

If you'd like to build with a packaged profile and include the b2g wrapper script, you can add the following to your mozconfig (with correct path):

GAIADIR=/path/to/gaia/repo

Then run make inside the mozilla-central directory:

$ make -f client.mk build

Note: Ensure you're using python2 and not python3 as the build will fail with python3.

The build will appear in ../build (or whatever MOZ_OBJDIR is set to in your .mozconfig) and will take a long time the first time you build.

On Linux, once it's built you can run B2G with:

# if you specified GAIADIR (e.g. Mozilla Nightlies)
$ ../build/dist/bin/b2g-bin -profile /path/to/gaia/profile

# if you did not specify GAIADIR
$ ../build/dist/bin/b2g -profile /path/to/gaia/profile

(substituting /path/to/gaia with the path to which you cloned Gaia).

On OSX, once it's built, you can run B2G with:

# if you specified GAIADIR (e.g. Mozilla Nightlies)
$ ../build/dist/B2G.app/Contents/MacOS/b2g-bin -profile /path/to/gaia/profile

# if you did not specify GAIADIR
$ ../build/dist/B2G.app/Contents/MacOS/b2g -profile /path/to/gaia/profile

When you want to update your own B2G Desktop build do:

$ hg pull && hg update
$ make -C ../build/b2g

In the gaia directory:

$ git pull

Simulating Hardware Buttons

On a desktop B2G build, you don't have access to hardware buttons, but you can simulate them:

Home button: fn + left arrow (OS X)
Power button: fn + right arrow (OS X)
Volume button: fn + up/down arrows (OS X)
open Cards View: cmd + fn + left arrow (OS X)

B2G on a device

It is possible to build & run Firefox OS on a limited number of smartphones. Please see documentation here.

There is also documentation here about testing changes on your device.

Unit Tests

Gaia comes with a suite of unit tests, which you can run using the built-in Test Agent app (by running it in B2G desktop, B2G on a device, or by navigating to http://test-agent.gaiamobile.org:8080 in Firefox Nightly).

See here for more information on writing and running unit tests for Gaia.

Filing Bugs

Bugs are filed on Bugzilla under Boot2Gecko > Gaia.

File a new bug under the Gaia component (or one of the sub-components) here

Contributing Code

Mozilla depends on contributions from the open source community to help develop Gaia apps and we'd love you to get involved.

Some great places to find some bugs to start hacking on:

Submitting a Patch

Assign an un-owned Gaia bug to yourself on Bugzilla (you'll need a Bugzilla account).
Fork Gaia on Github (you'll need a GitHub account) and clone your fork

$ git clone https://github.com/USERNAME/gaia.git gaia

Develop in a branch on your fork (remembering to keep to the Coding Style guidelines for Gaia)

$ git branch BRANCHNAME
$ git checkout BRANCHNAME

Commit your changes

$ git add /FILE/TO/ADD
$ git commit -m "COMMIT MESSAGE INCLUDING BUG NUMBER"

Push to your branch

$ git push origin BRANCHNAME

Send a pull request by navigating to the branch in your fork on GitHub and finding the pull request button
Paste a link to the pull request in the bug on Bugzilla
Your patch will be reviewed on Github (if it isn't getting reviewed try asking around on IRC or the mailing list or commenting on the bug)
To make changes in response to the code review, just push more commits to the same branch and your pull request will get updated automatically

$ git add /FILE/TO/ADD
$ git commit -m "COMMIT MESSAGE"
$ git push

(ideally squash all your changes into a single commit using git rebase)

Once the reviewer is happy with your patch, they will merge it into the master branch for you

(ideally the commit message should have r=REVIEWER_NAME added to the commit message of a the squashed commit and your patch includes a passing unit test)

Reviewers

Gaia now has module owners and peers! For code reviews, ask any of the peers listed here.

Coding Style

Background:

make sure HTML files are declared <!DOCTYPE html> (i.e., HTML5). IE9+ will load them in compatibility mode otherwise.

add a "use strict"; statement (exactly that!) to the top of your JS files

2 spaces for indentation - do not use tab.

Line break are free (I promise) don't hesitate to use them to separate logical block inside your functions.

Files are named like_this.js.

Use single quote instead of double quotes.

Additional rules:

Bad:

if (expression) doSomething();

Correct:

if (expression)
  doSomething();

System app

See here for some rules. https://groups.google.com/d/msg/mozilla.dev.gaia/rEhSrw6XmT4/UNvE7qW9pgYJ

Before submitting a patch

On each javascript files you are adding or you have modified, run:

gjslint --nojsdoc my_file.js

http://code.google.com/closure/utilities/docs/linter_howto.html

Set of smoke tests to run before you check-in a patch: PatchSmokeTests.pdf

Contacting The Team

Gaia Mailing List
#gaia IRC channel on irc.mozilla.org

Tips

Linux B2G Desktop support

The homescreen is empty

Currently, under Linux, OOP frame aren't rendered properly. The homescreen isn't actually rendered here...

If you just want to happily hack on pure UI (css and JS) you can safely run with OOP disabled and avoid those issues. Change the line in build/settings.py

 "debug.oop.disabled": False,

to

 "debug.oop.disabled": True,

Then rebuild your profile with

 $ rm -r profile && make

Port Forwarding

To forward the socket on the phone to the desktop (for desktop development), you first need to get rilproxy to expose it as such, rather than exposing it to Gecko. In the gaia directory:

 $ make forward

This runs the commands:

$ adb shell touch /data/local/rilproxyd
$ adb shell killall rilproxy
$ adb forward tcp:6200 localreserved:rilproxyd

The file located at /data/local/rilproxyd will be deleted once the rilproxy daemon will start again. As a consequence you have to do this manipulation every time your device restarts.

Restarting B2G on a device from the desktop

adb shell killall b2g

B2G Desktop JavaScript Console

You can run B2G Desktop with the JavaScript console by using the -jsconsole flag

$ /path/to/b2g-bin -jsconsole

Launching an app directly

A "--runapp" option has been added to the B2G Desktop command-line to automatically start an application. The system app is loaded and everything happens like normal; this is not like the old trick where we loaded your app instead of the system app.

"--runapp" takes an argument that it normalizes by lower-casing and removing dashes and spaces, and then checks the argument against the similarly normalized app names from app manifests. For example, the name of the e-mail app is currently "E-Mail", but "--runapp email" will run it. Partial matching is not supported right now, but you can enhance b2g/chrome/content/runapp.js if your app name is unwieldy.

If you invoke "--runapp" without an argument (or an empty argument), the command will print out a list of all the apps it knows about as well as a brief usage message.

One important note is that this command disables the lock-screen as part of its magic and does not re-enable it. The assumption is that you won't use this command on a profile where you are testing the lock screen, or will turn it back on manually. Feel free to enhance the command to behave better if this is a problem for you.

In summary:

./b2g -profile /path/to/your/gaia/profile --runapp email

runs the e-mail app.

reset-gaia and install-gaia make targets

The reset-gaia and install-gaia make targets can be used interchangeably. reset-gaia will purge all the existing profiles, database before push Gaia from your working directory (new setting database will also be initialized); install-gaia will just push updates of Gaia.

Blank screen when B2G Desktop starts

When you start b2g using b2g -profile $GAIA/profile a blank screen shows up and you see an error Cannot reach app://system.gaiamobile.org. To fix this there are a couple of things you can check

Rebuild the gaia profile using DEBUG=1 make profile in the $GAIA directory
Run b2g again
If this doesn't fix it, check if there is any other process listening on port 8080. The default profile of gaia starts httpd.js, which listens on port 8080. When running a debug profile, b2g connects to localhost:8080. If some other process is running on port 8080, b2g will fail to display the home screen of gaia
- To find out if this is the case, you can enable logging on httpd.js. The httpd.js in the profile resides in this location - $GAIA/profile/extensions/httpd/content/httpd.js. Edit the variable var DEBUG=false; to change the DEBUG to true. Save the file and restart b2g. On the console now, you will be able to view the httpd's logs

Diagnosing OOM problems

From Cjones:

Another way to diagnose possible OOMs is to open a terminal and run

$ watch -n 1 'adb shell b2g-procrank'

If you see the "USS" of one of the app processes go up near 100MB and then that process disappear from the process list (accompanied by some sort of visual crash in gaia), then you've almost certainly seen an OOM kill.