MozillaWiki

Gaia/Hacking

< Gaia
Revision as of 15:50, 23 August 2012 by Etienne s (talk | contribs) (→‎Running tests)

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

Quick start Instructions for running Gaia in a Nightly build 

  # Install a nightly version of Firefox from http://nightly.mozilla.org/

  # Clone the main gaia repository and generate a default set of apps/permissions
  git clone https://github.com/mozilla-b2g/gaia gaia
  cd gaia
  DEBUG=1 make

  # Start Gaia by telling Nightly where is the profile generated
  # IMPORTANT: Make sure all Firefox instances are closed before doing that.
  nightly -profile profile/ -no-remote http://system.gaiamobile.org:8080

  # Start making your changes!


If you want to go deeper, read the following instructions.

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

GAIA_DOMAIN = gaiamobile.org


ATTENTION - Desktop builds now available

There are now nightly builds of B2G desktop available here:

http://ftp.mozilla.org/pub/mozilla.org/b2g/nightly/latest-mozilla-central/

Please see this blog post for the related announcement of these builds. Using these builds only saves you from having to follow the steps in the Building B2G section below. You still need to checkout Gaia in order to create a profile for running the desktop builds: 

git clone git://github.com/mozilla-b2g/gaia
make -C gaia profile
/path/to/b2g -profile gaia/profile

From Ben's blog:

'Please note that these are NOT full B2G builds. These are developer-targeted builds which only run on desktop machines, and cannot be flashed onto a phone or tablet. These builds are primarily useful to developers, QA and localizers working on Gaia. They can also be used by anyone who wishes to test out their websites or apps through a B2G-like client..

As of July 13th, B2G Desktop Builds are working for Linux, Windows and OS X. 

An installer for windows that works out of the box is available from
https://github.com/downloads/sihorton/b2g-desktop-profile-installer/b2g-gaia-desktop.exe

Building B2G

Pull the code

 hg clone http://hg.mozilla.org/mozilla-central src
If you encounter an 'Command not found hg' you need to install Mercurial: https://developer.mozilla.org/en/Installing_Mercurial
git clone https://github.com/mozilla-b2g/gaia gaia

Update the code after the first time

In the mozilla-central directory: 

hg pull && hg update

In the Gaia directory: 

git fetch
git merge origin/master

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, the simplest thing to do is cd to the gaia repo directory and run b2g directly: 

$ DEBUG=1 make && B2G.app/Contents/MacOS/b2g -profile `pwd`/profile

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 seem to work fine on Linux )

Linux

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

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

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

Windows

For windows users a pre-built installer for b2g-desktop with pre-compiled gaia is available from 

https://github.com/downloads/sihorton/b2g-desktop-profile-installer/b2g-gaia-desktop.exe

a portable version (that extracts to a directory and does not create start menu entries) is also available: 

https://github.com/downloads/sihorton/b2g-desktop-profile-installer/b2g-portable.exe

If you want to update the included b2g-desktop to a newer version available from http://ftp.mozilla.org/pub/mozilla.org/b2g/nightly/latest-mozilla-central/ then extract the downloaded zip into the b2g-gaia-desktop directory the installer created for you.

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.

Unit tests

See https://developer.mozilla.org/en-US/docs/Mozilla/Boot_to_Gecko/Gaia_Unit_Tests

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 -profile /path/to/gaia/profile/directory


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

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.

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

IPv6

IPv6 can cause occasional slowdowns when running from a web server, you can fix this by disabling it in the user preferences 

   content += 'user_pref("network.dns.disableIPv6", true);\n';

Disabling updates

In bug 744989, Fabrice points out that you can disable gaia updates from gaiamobile.org by using the following commands: 

$ cd $GAIA
$ GAIA_DOMAIN=foo.org make install-gaia
$ adb push profile/user.js /data/b2g/mozilla/$$PROFILE_DIR$$/user.js

This is useful if one wants to, for example, do some sort of analysis on a particular build.

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

  1. Rebuild the gaia profile using DEBUG =1 make profile in the $GAIA directory
  2. Run b2g again
  3. 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
    1. 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
Retrieved from "https://wiki.allizom.org/index.php?title=Gaia/Hacking&oldid=463603"