Gaia/Hacking

From MozillaWiki
< Gaia
Revision as of 17:25, 6 March 2012 by Jrburke (talk | contribs) (Fix the git clone URL to be https, did not work with http)
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

# turn on mozTelephony/mozSms interfaces
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).

Mac

Build will fail on checking phase and complains about g++ and gcc executable not found. Please do the following first: 

 sudo ln -s /Developer/usr/bin/gcc /Developer/usr/bin/gcc-4.2
 sudo ln -s /Developer/usr/bin/g++ /Developer/usr/bin/g++-4.2

Running B2G

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.

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.

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!

Configuring your system

Until issue #165 is resolved you can ignore those steps


Configuring Apache

Locate the main configuration file of Apache aka httpd.conf and add the following entries: 

# load modules
LoadModule vhost_alias_module /usr/lib/apache2/modules/mod_vhost_alias.so
LoadModule expires_module /usr/lib/apache2/modules/mod_expires.so

# listen on port 8888
Listen 8888

ServerName gaiamobile.org
NameVirtualHost *:8888
UseCanonicalName Off

# Redirect [browser|sms|...].gaiamobile.org to ${GAIA}/apps/[browser|sms|...]/.
<VirtualHost *:8888>
ServerAlias *.gaiamobile.org
VirtualDocumentRoot /var/www/gaia/apps/%1/
ServerAlias gaiamobile.org
VirtualDocumentRoot /var/www/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>


If you find that apache2 fails to listen on port 8888. Add the following lines to your /etc/apache2/ports.conf file. 

NameVirtualHost *:8888
Listen 8888

Map ${DOMAIN_NAME} to localhost

Locate the main hosts file of your system [2] to map ${DOMAIN_NAME} to localhost and add the following lines: 

127.0.0.1    	gaiamobile.org browser.gaiamobile.org sms.gaiamobile.org camera.gaiamobile.org gallery.gaiamobile.org settings.gaiamobile.org dialer.gaiamobile.org homescreen.gaiamobile.org foo.gaiamobile.org

For the example the main hosts file on unix/linux systems is /etc/hosts.

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.

First locate your profile folder [3] 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 [4] for help.


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 edit the ${PROFILE}/prefs.js file while the B2G application is closed (this is important if you don't want your changes to be overwritten) and add lines like: 

user_pref(my.pref.name, true);

First go to MDC development preferences and set up the preferences declared there.

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://dev.wikimo.nonprod.webservices.mozgcp.net/index.php?title=Gaia/Hacking&oldid=404559"