Gaia/Hacking

From MozillaWiki
< Gaia
Revision as of 21:33, 27 March 2012 by Rillian (talk | contribs) (→‎Mac: This is fixed -- Bug 697881)
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

PROFILE = PATH_TO_PROFILE

Building B2G

Pull the code

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

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
ac_add_options --enable-b2g-ril

# turn on marionette
ac_add_options --enable-marionette

Add user.js to profile

Find the profile folder:

http://kb.mozillazine.org/Profile_folder_-_Firefox#Navigating_to_the_profile_folder

Replace "Firefox" with "B2G" to find the B2G profile folder. Inside the default profile, create a file user.js with: 

pref("marionette.defaultPrefs.enabled", true);
pref("b2g.remote-js.enabled", true);
pref("b2g.remote-js.port", 4242);
pref("javascript.options.showInConsole", true);
pref("nglayout.debug.disable_xul_cache", true);
pref("browser.dom.window.dump.enabled", true);
pref("javascript.options.strict", true);
pref("dom.report_all_js_exceptions", true);
pref("nglayout.debug.disable_xul_fastload", true);

Marionette will listen on port 2828, and if you include the remote-js.enabled and port lines, you will be able to telnet to localhost 4242 (or whatever port you desire) to get an interactive javascript REPL.

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

Running B2G

NOTE: section is out of date and can be safely skipped.

Desktop

declare -x B2G_HOMESCREEN=file://${GAIA}/homescreen.html
../build/dist/bin/b2g

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

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

Create B2G Profile at the Specified Location

The B2G profile can be create at the specific location. To do that execute b2g with following arguments: 

../build/dist/bin/b2g -ProfileManager

On the Choose User Profile screen, the default profile can be removed and a new profile can be created at the specified location.

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: 

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

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

Also in order to run the mozTelphony related tests make sure that the prefs in your b2g/app/b2g.js refers to 

 http://localhost:7777/apps/dialer/dialer.html

And not something with /data/local/apps/

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!

Hosting Gaia on your own machine

For development you might find it helpful to host Gaia apps on your own machine. 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.

Set up Apache

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

$ sudo apt-get install apache2

Enable virtual hosts by changing the first line of /etc/apache2/sites-available/default from: 

<VirtualHost *:80>

to: 

NameVirtualHost *
<VirtualHost *>

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>

Note: the "ExpiresByType" rules will prevent Apache from caching. Make sure you have properly disabled the cache on your client (i.e. browser.cache.offline.enable should be set to false, as mentioned at the end of this document).

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

Point gaiamobile.org at your machine

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

127.0.0.1     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

Note: not all of these are required any more, needs updating.

Now you should be able to point your web browser at homescreen.gaiamobile.org and get the homscreen.

Configure your device to load Gaia from your development machine

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)

Note: not all of these are required any more, needs updating.

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!

Tell B2G which Web Applications are installed (aka avoid the empty homescreen)

At this point B2G should startwith an empty homescreen.


In order for B2G to know which applications are available on your system you need to declare them in the profile folder of B2G.

All the necessary files live in ${GAIA}/profile/webapps so the only thing you need to do is to make a link between this folder and ${PROFILE}/webapps.

To generate the ${GAIA}/profile/webapps and ${GAIA}/profile/OfflineCache folders, execute: 

 make -C ${GAIA} copy-manifests
 make -C ${GAIA} offline

First locate your profile folder [2] and then execute the following lines: 

ln -s ${GAIA}/profile/webapps ${PROFILE}/webapps
ln -s ${GAIA}/profile/OfflineCache ${PROFILE}/OfflineCache

|ln| is the standard way to make link on unix/linux systems. The method of creating such a link can vary depending on your system, see [3] for help.

The homescreen can be pointed to http://homescreen.gaiamobile.org/: 

 declare -x B2G_HOMESCREEN=http://homescreen.gaiamobile.org/

Restart B2G 

../build/dist/bin/b2g

Tips

Preferences

There are many preferences used in B2G. Here are the most useful ones you need to know while hacking on top of it.

There is no about:config page in B2G so you will need to create or edit the ${PROFILE}/user.js file and add lines like: 

user_pref(my.pref.name, true);

Further up this page, in the section https://wiki.mozilla.org/Gaia/Hacking#Add_user.js_to_profile there is a user.js file which will set many useful debugging preferences. Many of these are from here: MDC development preferences.

If you want to disable the offline cache use: 

user_pref('browser.cache.offline.enable', false);

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.

Retrieved from "https://wiki.allizom.org/index.php?title=Gaia/Hacking&oldid=412732"