Gaia/Hacking: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
(Redirected page to mdn:Firefox OS/Developing Gaia)
 
(57 intermediate revisions by 24 users not shown)
Line 1: Line 1:
Inside Gaia everything is a Web Application, see {{MDN|Apps|Apps on MDN}}.
#REDIRECT [[mdn:Firefox OS/Developing Gaia]]
 
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 [http://mxr.mozilla.org/mozilla-central/source/dom/interfaces/apps/nsIDOMApplicationRegistry.idl].
 
Quick start Instructions for running Gaia in a Nightly build
 
<pre class="_fck_mw_lspace">
  # 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!
</pre>
 
 
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/ http://ftp.mozilla.org/pub/mozilla.org/b2g/nightly/latest-mozilla-central/]
 
Please see [http://blog.mozilla.org/bhearsum/archives/320 this blog post] for the related announcement of these builds.  Using these builds only saves you from having to follow the steps in the [[Gaia/Hacking#Building_B2G|''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:
 
<blockquote>'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.. ''</blockquote>
 
'''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 ===
<pre class="_fck_mw_lspace"> 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
 
I
</pre>
<h3> Update the code after the first time </h3>
<p>In the mozilla-central directory:
</p>
<pre class="_fck_mw_lspace">hg pull &amp;&amp; hg update
</pre>
<p> In the Gaia directory:
<pre class="_fck_mw_lspace">git fetch
git merge origin/master
</pre>
</p>
 
=== Create a mozconfig ===
<p>Create a file named "mozconfig" in the mozilla-central directory.
Here's an example mozconfig.
</p>
<pre class="_fck_mw_lspace">mk_add_options MOZ_OBJDIR=../build
mk_add_options MOZ_MAKE_FLAGS=&quot;-j9 -s&quot;
 
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
</pre>
=== Build ===
<p>In the mozilla-central directory:
</p>
<pre class="_fck_mw_lspace">make -f client.mk build
</pre>
<p>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.
</p>
 
== 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 [https://developer.mozilla.org/en/Marionette Marionette]. You can set up Marionette with [https://developer.mozilla.org/en/Marionette/Setup#Running_Marionette_on_Desktop_Firefox_or_B2G_Desktop_builds B2G Desktop] or for [https://developer.mozilla.org/en/Marionette/Setup#Running_B2G_and_Marionette_on_an_emulator_or_device 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 {{MDN|Mochitest#Test_functions}}
 
For more information about browser-chrome tests, please refer to {{MDN|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 -profile /path/to/gaia/profile/directory
 
<!--
HIDE THIS PART -- bug has landed
 
 
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 {{bug|722197}} is fixed.
 
Edit '''/etc/hosts''' (or [http://en.wikipedia.org/wiki/Hosts_%28file%29#Location_in_the_file_system somewhere else] on other systems) and add the following lines
 
127.0.0.1    gaiamobile.org
127.0.0.1    homescreen.gaiamobile.org
127.0.0.1    dialer.gaiamobile.org
127.0.0.1    sms.gaiamobile.org
127.0.0.1    browser.gaiamobile.org
127.0.0.1    maps.gaiamobile.org
127.0.0.1    camera.gaiamobile.org
127.0.0.1    gallery.gaiamobile.org
127.0.0.1    video.gaiamobile.org
127.0.0.1    market.gaiamobile.org
127.0.0.1    music.gaiamobile.org
127.0.0.1    settings.gaiamobile.org
127.0.0.1    clock.gaiamobile.org
127.0.0.1    crystalskull.gaiamobile.org
127.0.0.1    penguinpop.gaiamobile.org
127.0.0.1    towerjelly.gaiamobile.org
127.0.0.1    wikipedia.gaiamobile.org
127.0.0.1    cnn.gaiamobile.org
127.0.0.1    bbc.gaiamobile.org
127.0.0.1    nytimes.gaiamobile.org
127.0.0.1    calculator.gaiamobile.org
127.0.0.1    system.gaiamobile.org
 
([http://www.justincarmony.com/blog/2011/07/27/mac-os-x-lion-etc-hosts-bugs-and-dns-resolution/ OSX has issues with single lines with multiple domains])
 
-->
 
=== 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 <code>DEBUG=1 make</code>''
 
=== Javascript Console ===
You can open the Javascript Console by running:
../build/dist/bin/b2g -jsconsole
 
=== Launching an App Directly ===
 
Want B2G desktop to directly launch your?  You want these preference lines to your profile/user.js file.  Because this file gets regenerated when you run "make profile", it is best to add these to custom-prefs.js (in the root of the gaia dir) if you want the preferences to be sticky:
 
  user_pref("browser.homescreenURL","http://myapp.gaiamobile.org:8080");
  user_pref("browser.startup.homepage", "http://myapp.gaiamobile.org:8080");
 
You will need to remove the preferences if you want to be able to use the homescreen again.
 
=== 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 <code>reset-gaia</code> and <code>install-gaia</code> make targets can be used interchangeably. <code>reset-gaia</code> will purge all the existing profiles, database before push Gaia from your working directory (new setting database will also be initialized); <code>install-gaia</code> will just push updates of Gaia.

Latest revision as of 02:50, 25 October 2014

Redirect to:

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