Gaia/Hacking

From MozillaWiki
Jump to navigation Jump to search

Inside Gaia everything is a Web Application, see Apps on MDN.

When Gaia starts, the homescreen application is the first application displayed on the screen.

The homescreen application reads all installed web applications and shows an icon for each. This is done by using the window.navigator.mozApps object that exposes the Application Registry API [1].

Gaia can be run in 3 different ways, each one requiring some specific steps to be set-up:

  • inside a web browser such a Firefox
  • inside a device emulator
  • on the device

Throughout these instructions the following is assumed: 

GAIA = PATH_TO_GAIA_REPOSITORY

DOMAIN_NAME = gaiamobile.org

Building B2G

Pull the code 

 hg clone http://hg.mozilla.org/mozilla-central src
 git clone https://github.com/andreasgal/gaia gaia

Update the code after the first time

In the mozilla-central directory: 

hg pull && hg update

In the Gaia directory: 

git fetch

Create a mozconfig

Create a file named "mozconfig" in the mozilla-central directory. Here's an example mozconfig. 

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

Build

In the mozilla-central directory: 

make -f client.mk build

The build will appear in ../build (or whatever MOZ_OBJDIR is set to in your mozconfig). Be sure you're using python2 and not python3 as build will fail with python3.


Running B2G

Desktop

The next steps will generate a profile that contains an Application cache version of Gaia and a pre-populated list of installed applications by mozApps. This profile will then be used by B2G to start the homescreen and populate it with apps. 

# generate the profile/ folder
cd ${GAIA}
make

# Run b2g with the generated profile
../build/dist/bin/b2g -profile ${GAIA}/profile

You may want to add the $MOZ_OBJDIR/dist/bin directory to your shell's $PATH and B2G_HOMESCREEN to your shell environment so you can just type "b2g" anywhere.

Mac

For Mac users, please run 

../build/dist/B2G.app/Contents/MacOS/b2g -profile ${GAIA}/profile

instead. In ./bin/b2g all the keyboard/mouse event will be redirect to Terminal for unknown reason.

As well, b2g seems to prefer an absolute path to the profile directory ( relative paths to the profile sem to work fine on Linux )

Linux

Linux users can experience annoying rendering glitches. To avoid them, pleas add 

user_pref("layers.acceleration.disabled", true);

to your ${GAIA}/profile/prefs.js file.

Running tests

There is a dedicated test framework for B2G called Marionette. You can set up Marionette with B2G Desktop or for an emulator or device.

Desktop

If you are running a desktop build you can also write browser-chrome tests.

Running tests

Be sure to have MOZ_OBJDIR define in your shell environment. MOZ_OBJDIR should point to your b2g desktop build directory - the one specified in the .mozconfig file. 

 cd $GAIA
 DEBUG=1 make
 MOZ_OBJDIR=PATH/TO/THE/BUILD/DIR make mochitest

The desktop build of b2g should be lanched with a new window containing the result of the tests run.

Caveat

The test tools will be looking for an executable at path 

 $MOZ_OBJDIR/dist/B2G.app/Contents/MacOS/b2g-bin
 on a mac, or
 $MOZ_OBJDIR/dist/bin/b2g-bin
 on linux

Which isn't generated by the build. So you'll have to symlink your b2g binary to b2g-bin. 

 cd $MOZ_OBJDIR/dist/B2G.app/Contents/MacOS
 # or
 cd $MOZ_OBJDIR/dist/bin
 
 ln -s b2g b2g-bin

Writing tests

For more information about Mochitest, please refer to Mochitest#Test_functions

For more information about browser-chrome tests, please refer to Browser_chrome_tests

New browser-chrome tests should be put directly in the $GAIA/tests/ directory. There is already a few of them there that you can look at to have a better idea about how to write yours!

Loading Gaia from a server

Desktop

For development you might find it helpful to load Gaia from a web server instead of relying on the application cache.

First you need to generate a profile that does not rely on the Application Cache. From your Gaia directory run: 

DEBUG=1 make

The generated profile directory also contains a web server. When you run B2G desktop using this profile the web server will run on port 8080... 

b2g -p /path/to/gaia/profile/directory

Currently you also need to map all the subdomains to localhost to get B2G to load gaiamobile.org from your own machine.

Note: This will not be needed any more once https://bugzilla.mozilla.org/show_bug.cgi?id=722197 is fixed.

Edit /etc/hosts (or somewhere else on other systems) and add the following line 

127.0.0.1     gaiamobile.org homescreen.gaiamobile.org dialer.gaiamobile.org sms.gaiamobile.org browser.gaiamobile.org maps.gaiamobile.org camera.gaiamobile.org gallery.gaiamobile.org video.gaiamobile.org market.gaiamobile.org music.gaiamobile.org settings.gaiamobile.org clock.gaiamobile.org crystalskull.gaiamobile.org penguinpop.gaiamobile.org towerjelly.gaiamobile.org wikipedia.gaiamobile.org cnn.gaiamobile.org bbc.gaiamobile.org nytimes.gaiamobile.org calculator.gaiamobile.org

Device

Pull the hosts file from the device 

$ adb pull /system/etc/hosts

add the line to the hosts file 

192.168.1.3     gaiamobile.org dialer.gaiamobile.org sms.gaiamobile.org browser.gaiamobile.org maps.gaiamobile.org camera.gaiamobile.org gallery.gaiamobile.org video.gaiamobile.org market.gaiamobile.org music.gaiamobile.org settings.gaiamobile.org clock.gaiamobile.org crystalskull.gaiamobile.org penguinpop.gaiamobile.org towerjelly.gaiamobile.org wikipedia.gaiamobile.org cnn.gaiamobile.org bbc.gaiamobile.org nytimes.gaiamobile.org calculator.gaiamobile.org

(where 192.168.1.3 is the static IP of your development box on your network)

Push the hosts file back to the device 

adb push hosts /system/etc/hosts

Reboot the device and if Wifi is configured it should load the homescreen from your desktop machine!

Tips

Using a different domain

You can easily use a different domain when using Gaia: 

GAIA_DOMAIN=mydomain.org 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 the b2g application

To reload/restart b2g everything simply enter the command: 

adb shell killall b2g

Using Firefox instead of B2G to launch Gaia

While the b2g build has more features than Firefox you can use try to use Firefox to develop if you don't need the additional features offered by the b2g build (Please note that these features will land in Firefox too one day). Instead of using b2g on the command line to launch Gaia, just use firefox: 

firefox -profile ${GAIA_DIR} -no-remote http://homescreen.gaiamobile.org:8080

Note: this will work with the port specification assuming you have run DEBUG=1 make

Javascript Console

You can open the Javascript Console by running: 

../build/dist/bin/b2g -jsconsole

Touch events

To enable the necessary interfaces in the Firefox web browser you need to go to about:config and add the boolean preference dom.w3c_touch_events.enabled and set it to true.

Hosting Gaia using Apache

As an alternative to B2G's own web server, you may find it helpful to host Gaia apps using your own Apache web server. Below is a quick guide on how to set that up, this is based on Ubuntu but should work on other platforms with a few modifications.

If you haven't already installed Apache, you should install it 

$ sudo apt-get install apache2

Enable virtual hosts by changing the first two lines of /etc/apache2/sites-available/default to: 

NameVirtualHost *
<VirtualHost *>

(Note that the first line is new, the second line should replace the first line in the default version of that file)

Create a virtual host config at /etc/apache2/sites-available/gaiamobile.org 

# Redirect [browser|sms|...].gaiamobile.org to ${GAIA}/apps/[browser|sms|...]/.
<VirtualHost *>
  ServerName  homescreen.gaiamobile.org
  ServerAlias *.gaiamobile.org
  VirtualDocumentRoot /path/to/gaia/apps/%1/
</VirtualHost>

<VirtualHost *>
  ServerName gaiamobile.org
  ServerAlias gaiamobile.org
  DocumentRoot /path/to/gaia
</VirtualHost>

# Add the correct mimetypes for offline cache manifest
AddType text/cache-manifest .appcache

# Prevent Apache from caching apps files
<IfModule mod_expires.c>
  ExpiresActive on
  ExpiresDefault "access plus 0 hours"
  ExpiresByType text/html "access plus 0 hours"
  ExpiresByType text/xml "access plus 0 hours"
  ExpiresByType text/css "access plus 0 hours"
  ExpiresByType text/plain "access plus 0 hours"
  ExpiresByType application/x-javascript "access plus 0 hours"
  ExpiresByType application/javascript "access plus 0 hours"
  ExpiresByType text/javascript "access plus 0 hours"
  ExpiresByType text/cache-manifest "access plus 0 hours"
  ExpiresByType image/gif "access plus 0 hours"
  ExpiresByType image/png "access plus 0 hours"
  ExpiresByType image/jpeg "access plus 0 hours"
  ExpiresByType image/x-icon "access plus 0 hours"
</IfModule>

Enable the Apache modules 

$ sudo a2enmod expires
$ sudo a2enmod vhost_alias

Enable the gaiamobile.org virtual host 

$ sudo a2ensite gaiamobile.org

Restart Apache 

$ sudo apache2ctl graceful
Retrieved from "https://wiki.allizom.org/index.php?title=Gaia/Hacking&oldid=425670"