Hacking Gaia

  • Revision slug: Mozilla/Firefox_OS/Platform/Gaia/Hacking
  • Revision title: Hacking Gaia
  • Revision id: 386613
  • Created:
  • Creator: Julen
  • Is current revision? No
  • Comment Fixed link.

Revision Content

This page is targeted at Gaia developers. If you're looking for informations about how to build and run Firefox OS, you should consult the Building and installing Firefox OS page instead.

Gaia is the collection of web apps which make up the front end of Firefox OS. Everything you see on the screen in Firefox OS is built using open Web technologies. This includes the home screen and all the default apps.

Getting the source

To get the source code for Gaia, fork us on GitHub and then clone your fork using git.

$ git clone https://github.com/mozilla-b2g/gaia.git

Running Gaia

You can either run Gaia on the desktop, or on a compatible mobile device.

B2G desktop

B2G desktop is a desktop build of the app runtime used on Firefox OS devices which you can use to run Gaia on your desktop computer.

You can download a nightly build of B2G desktop from here. Depending on what version you are targeting, you may want a specific version of latest-mozilla-b2g18. There are builds for Linux (32 bit and 64 bit), Mac OS X and Windows.

Nightly builds come packaged with a recent version of gaia. Once you've downloaded the archive, all your need to do is extract it to a folder and run the b2g binary from the extracted folder.

Note: 64-bit Linux builds do not currently work on some distributions, this is {{bug(812484)}}. If you have problems try a 32-bit build instead.

$ cd b2g
$ ./b2g

To run B2G with your own version of Gaia for development purposes you first need build a profile from your clone:

$ cd /path/to/gaia
$ DEBUG=1 make

This will generate a directory in your gaia directory called profile. The DEBUG part runs Gaia as hosted apps on a built-in web server, rather than the default packaged apps which have to be re-packaged after every change.

You can then run B2G Desktop with your generated profile like so:

$ /path/to/gaia/profile

If you want to you can build your own B2G desktop from source.

Using Gaia on a device

If you have a compatible mobile device you can also run Gaia by flashing it with Firefox OS. See Building and installing Firefox OS for details on how to do this. We also have documentation for how to test Firefox OS.

Unit tests

See Gaia unit tests for documentation about how to create and run unit tests for Gaia.

Filing bugs

Bugs are filed on Bugzilla under Boot2Gecko > Gaia. File a new bug under the Gaia component (or one of the sub-components).

Contributing to Gaia

Mozilla depends on contributions from the open source community to help develop Gaia apps and we'd love you to get involved.

Some great places to find some bugs to start hacking on:

Coding style basics

  • Background:
  • Make sure HTML files are declared <!DOCTYPE html> (that is, as HTML5 documents). If you don't, Internet Explorer 9 and later will load them in compatibility mode.
  • Include the "use strict"; statement (just like that, including the quotes) to the top of your JavaScript files to put them into strict mode.
  • Always use two spaces for indentation, rather than tabs.
  • Please use line breaks to separate logical bits of code!
  • Multi-word file names should use the "underscore" character to separate words, like_this.js.
  • Use single quotes instead of double quotes for strings.

Additional rules

Bad:

if (expression) doSomething();

Correct:

if (expression)
  doSomething();

If you're working on the system app, check out the guidance listed here.

Before submitting a patch we recommend you run gjslint on it to check for any style errors:

gjslint --nojsdoc my_file.js

Submitting a patch

First file or assign a bug to yourself on Bugzilla, you'll need a Bugzilla account.

Then create a branch on your fork of Gaia:

$ git branch branchname
$ git checkout branchname

Commit your changes:

$ git add /file/to/add
$ git commit -m "commit message including bug number"

Push your branch:

$ git push origin branchname

Send a pull request by navigating to the branch in your fork on GitHub and finding the pull request button.

To request a review of your patch, add an attachment to the bug in Bugzilla referencing the URL of the pull request and set the review ("r") flag to "?" and enter the bugzilla ID of one of the module owners and peers.

The reviewer may ask you to make some changes. Once they're is happy with your patch, they will merge it into the master branch for you. Before they do this they would prefer it if you could squash all your changes into a single commit and add "r=reviewername" to the end of the commit message.

Contacting the Team

Revision Source

<div class="warning">
  <p>This page is targeted at Gaia developers. If you're looking for informations about how to build and run Firefox OS, you should consult the <a href="/en-US/docs/Mozilla/Firefox_OS/Building_and_installing_Firefox_OS" title="/en-US/docs/Mozilla/Firefox_OS/Building_and_installing_Firefox_OS">Building and installing Firefox OS page</a> instead.</p>
</div>
<p>Gaia is the collection of <a href="https://developer.mozilla.org/apps" rel="nofollow">web apps</a> which make up the front end of <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Firefox_OS">Firefox OS</a>. Everything you see on the screen in Firefox OS is built using open Web technologies. This includes the home screen and all the default apps.</p>
<h2 id="Getting_the_source">Getting the source</h2>
<p>To get the source code for Gaia, <a href="https://github.com/mozilla-b2g/gaia" title="https://github.com/mozilla-b2g/gaia">fork us on GitHub</a> and then clone your fork using <a href="http://git-scm.com/" title="http://git-scm.com/">git</a>.</p>
<pre>
$ git clone https://github.com/mozilla-b2g/gaia.git</pre>
<h2 id="Running_Gaia">Running Gaia</h2>
<p>You can either run Gaia on the desktop, or on a compatible mobile device.</p>
<h3 id="B2G_desktop">B2G desktop</h3>
<p>B2G desktop is a desktop build of the app runtime used on Firefox OS devices which you can use to run Gaia on your desktop computer.</p>
<p>You can download a nightly build of B2G desktop from <a href="http://ftp.mozilla.org/pub/mozilla.org/b2g/nightly/" title="http://ftp.mozilla.org/pub/mozilla.org/b2g/nightly/">here</a>. Depending on what version you are targeting, you may want a specific version of latest-mozilla-b2g18. There are builds for Linux (32 bit and 64 bit), Mac OS X and Windows.</p>
<p>Nightly builds come packaged with a recent version of gaia. Once you've downloaded the archive, all your need to do is extract it to a folder and run the b2g binary from the extracted folder.</p>
<div class="note">
  <p><strong>Note:</strong> 64-bit Linux builds do not currently work on some distributions, this is {{bug(812484)}}. If you have problems try a 32-bit build instead.</p>
</div>
<pre>
$ cd b2g
$ ./b2g</pre>
<p>To run B2G with your own version of Gaia for development purposes you first need build a profile from your clone:</p>
<pre>
$ cd /path/to/gaia
$ DEBUG=1 make</pre>
<p>This will generate a directory in your <code>gaia</code> directory called <code>profile</code>. The <code>DEBUG</code> part runs Gaia as hosted apps on a built-in web server, rather than the default packaged apps which have to be re-packaged after every change.</p>
<p>You can then run B2G Desktop with your generated profile like so:</p>
<pre>
$ /path/to/gaia/profile</pre>
<p>If you want to you can build your own B2G desktop from source.</p>
<h3 id="Using_Gaia_on_a_device">Using Gaia on a device</h3>
<p>If you have a compatible mobile device you can also run Gaia by flashing it with Firefox OS. See <a href="/en-US/docs/Mozilla/Firefox_OS/Building_and_installing_Firefox_OS" title="Mozilla/Firefox_OS/Building_and_installing_Firefox_OS">Building and installing Firefox OS</a> for details on how to do this. We also have documentation for <a href="/en-US/docs/Mozilla/Firefox_OS/Platform/Testing" title="https://developer.mozilla.org/en-US/docs/Mozilla/Firefox_OS/Platform/Testing">how to test Firefox OS</a>.</p>
<h2 id="Unit_tests">Unit tests</h2>
<p>See <a href="/en-US/docs/Mozilla/Firefox_OS/Platform/Testing/Gaia_unit_tests" title="Mozilla/Firefox_OS/Platform/Testing/Gaia_unit_tests">Gaia unit tests</a> for documentation about how to create and run unit tests for Gaia.</p>
<h2 id="Filing_bugs">Filing bugs</h2>
<p>Bugs are filed on Bugzilla under <a href="https://bugzilla.mozilla.org/buglist.cgi?product=Boot2Gecko&amp;component=Gaia&amp;resolution=---" rel="nofollow">Boot2Gecko &gt; Gaia</a>. File a new bug <a href="https://bugzilla.mozilla.org/enter_bug.cgi?product=Boot2Gecko" title="https://bugzilla.mozilla.org/enter_bug.cgi?product=Boot2Gecko">under the Gaia component</a> (or one of the sub-components).</p>
<h2 id="Contributing_to_Gaia">Contributing to Gaia</h2>
<p>Mozilla depends on contributions from the open source community to help develop Gaia apps and we'd love you to get involved.</p>
<p>Some great places to find some bugs to start hacking on:</p>
<ul>
  <li><a href="https://bugzilla.mozilla.org/buglist.cgi?quicksearch=component:gaia%20sw:polish%20@nobody;list_id=4566236" rel="nofollow">Unowned Gaia polish bugs on Bugzilla</a></li>
  <li><a href="http://www.joshmatthews.net/bugsahoy/?b2g=1" rel="nofollow">Mentored bugs</a></li>
</ul>
<h3 id="Coding_style_basics">Coding style basics</h3>
<ul>
  <li>Background:
    <ul>
      <li><a href="/en-US/docs/Developer_Guide/Coding_Style#General_practices" title="Developer_Guide/Coding_Style#General_practices">Coding Style: General practices</a></li>
      <li><a href="/en-US/docs/Developer_Guide/Coding_Style#JavaScript_practices" title="Developer_Guide/Coding_Style#JavaScript_practices">Coding Style: JavaScript practices</a></li>
      <li><a href="/en-US/docs/Developer_Guide/Coding_Style#Naming_and_formatting_guide" title="Developer_Guide/Coding_Style#Naming_and_formatting_guide">Coding Style: Naming and formatting guide</a></li>
    </ul>
  </li>
  <li>Make sure HTML files are declared <code>&lt;!DOCTYPE html&gt;</code> (that is, as HTML5 documents). If you don't, Internet Explorer 9 and later will load them in compatibility mode.</li>
  <li>Include the <code>"use strict";</code> statement (just like that, including the quotes) to the top of your JavaScript files to put them into strict mode.</li>
  <li>Always use two spaces for indentation, rather than tabs.</li>
  <li>Please use line breaks to separate logical bits of code!</li>
  <li>Multi-word file names should use the "underscore" character to separate words, <code>like_this.js</code>.</li>
  <li>Use single quotes instead of double quotes for strings.</li>
</ul>
<h4 id="Additional_rules">Additional rules</h4>
<p>Bad:</p>
<pre>
if (expression) doSomething();
</pre>
<p>Correct:</p>
<pre>
if (expression)
  doSomething();</pre>
<p>If you're working on the system app, check out the guidance listed <a href="https://groups.google.com/d/msg/mozilla.dev.gaia/rEhSrw6XmT4/UNvE7qW9pgYJ" title="See_here_for_some_rules._https://groups.google.com/d/msg/mozilla.dev.gaia/rEhSrw6XmT4/UNvE7qW9pgYJ">here</a>.</p>
<p>Before submitting a patch we recommend you run <a href="http://closure-linter.googlecode.com/svn/trunk/closure_linter/gjslint.py" title="http://closure-linter.googlecode.com/svn/trunk/closure_linter/gjslint.py">gjslint</a> on it to check for any style errors:</p>
<pre>
gjslint --nojsdoc my_file.js</pre>
<h3 id="Submitting_a_patch">Submitting a patch</h3>
<p>First file or assign a bug to yourself on <a href="https://bugzilla.mozilla.org/buglist.cgi?product=Boot2Gecko&amp;component=Gaia&amp;resolution=---" title="https://bugzilla.mozilla.org/buglist.cgi?product=Boot2Gecko&amp;component=Gaia&amp;resolution=---">Bugzilla</a>, you'll need a Bugzilla account.</p>
<p>Then create a branch on your fork of Gaia:</p>
<pre>
$ git branch branchname
$ git checkout branchname</pre>
<p>Commit your changes:</p>
<pre>
$ git add /file/to/add
$ git commit -m "commit message including bug number"</pre>
<p>Push your branch:</p>
<pre>
$ git push origin branchname</pre>
<p>Send a pull request by navigating to the branch in your fork on GitHub and finding the pull request button.</p>
<p>To request a review of your patch, add an attachment to the bug in Bugzilla referencing the URL of the pull request and set the review ("r") flag to "?" and enter the bugzilla ID of one of the <a href="https://wiki.mozilla.org/Modules/FirefoxOS" title="https://wiki.mozilla.org/Modules/FirefoxOS">module owners and peers</a>.</p>
<p>The reviewer may ask you to make some changes. Once they're is happy with your patch, they will merge it into the master branch for you. Before they do this they would prefer it if you could squash all your changes into a single commit and add "r=reviewername" to the end of the commit message.</p>
<h2 id="Contacting_the_Team">Contacting the Team</h2>
<ul>
  <li><a href="https://lists.mozilla.org/listinfo/dev-gaia" rel="nofollow">Gaia Mailing List</a></li>
  <li>#gaia IRC channel on irc.mozilla.org</li>
</ul>
Revert to this revision