MDN may have intermittent access issues April 18 13:00 - April 19 01:00 UTC. See whistlepig.mozilla.org for all notifications.

mozilla

Revision 646183 of Running the Gaia codebase

  • Revision slug: Mozilla/Firefox_OS/Developing_Gaia/Running_the_Gaia_codebase
  • Revision title: Running the Gaia codebase
  • Revision id: 646183
  • Created:
  • Creator: chrisdavidmills
  • Is current revision? No
  • Comment

Revision Content

This article runs through in detail how to run the Gaia codebase locally, and what tools are available in this setup.

To start with, we should point out that you DON'T have to build Gecko, or B2G, to contribute to Gaia. You just need to download the Gaia source code and have the ability to run and edit it in some way.

There are several different ways to run Gaia:

  • Flash your phone with an updated Gaia build.
  • Launch your Gaia inside a B2G Desktop build.
  • Run your Gaia inside the App Manager/Firefox Simulator.
  • Launch Gaia inside Desktop Firefox (Nightly is recommended).

You can find concise information on running it in these different ways on our Different ways to run Gaia page, along with links to more detailed information as required. In general these are ordered from most complex (but most realistic experience provided) to easiest (but least realistic).

In this article we'll be concentrating on running Gaia inside Desktop Firefox — for most changes you'll want to make to the Gaia codebase, this offers the quickest mechanism for testing updates, but obviously there are some features (such as testing device APIs or interaction with phone hardware) that will need a real device.

Note: To get further help with Gaia, the best places to go are the #gaia IRC channel (see Mozilla IRC for more information) and the dev-gaia mailing list.

Running Gaia in Desktop Firefox

  1. First, make a fork of the main Gaia repo on Github.
  2. Next, clone your fork locally:
    git clone https://github.com/your-username/gaia.git
  3. Add the upstream like this:
    cd gaia
    git remote add upstream https://github.com/mozilla-b2g/gaia
  4. Next, install the Fira Sans font on your system: this is the font Gaia uses on real devices, so it is useful to have it available to use when running Gaia on desktop too, especially when you are trying to debug issues related to overflow or font-sizing, for example.
  5. Now you need to create a debug profile of Gaia. Running DEBUG=1 make inside your repo folder creates a profile in the profile-debug directory, which is setup for optimal debugging. It creates unpackaged (hosted versions) of the Gaia apps that can be served directly via the local HTTPD server bundled along with Firefox desktop as an extension. When you make a change you just need to refresh your browser window to see the result (as you'll see later), rather than having to rebuild the profile, repush it to the device, etc. This is really good for rapid CSS/JS/HTML hacking.
  6. With your debug profile built, run it in your desktop Firefox build (we'd recommend you use Firefox Nightly) from the command line, using a command with the following structure:
    /path/to/firefoxnightly -profile /path/to/B2G/gaia/profile-debug -no-remote
    For example, on OS X, we ran the following command:
    /Applications/FirefoxNightly.app/Contents/MacOS/firefox -profile /Users/bob/git/gaia/profile-debug -no-remote

This should load up your Gaia profile running in a desktop Firefox tab, like so (you'll notice that the URL is http://system.gaiamobile.org:8080/):

A screenshot of Firefox OS Gaia being run inside a desktop Firefox nightly build.

Note: If you open a tab in the Firefox desktop window Gaia is running in, enter about:config, and search for "gaia", you'll find a number of extensions.gaia.* prefs — which the httpd.js extension is using. You'll also be able to find the network.dns.localDomains pref, which is the trick that makes http://system.gaiamobile.org:8080 connect on your localhost.

Note: The make command is run inside the Gaia directory to create a profile (including apps, setting, etc.) that can be loaded on a phone, run inside an emulator, etc. The make command has a number of options to create different kinds of build. Just running make creates a standard production profile inside gaia/make, with packaged apps, which is not set up for optimum modification and debugging.

Available tools

You'll see that this view has a number of different tools available, including:

  • Responsive design view in the top left corner.
  • All the standard Firefox Toolbox debugging tools available to the right of the screen (by default; this can be moved to the bottom of the screen if you like, but on the right makes more sense when debugging the small screen display on the left.)
  • A special Firefox OS tools tab on the toolbox that provides some specific tools for debugging Firefox OS in this mode:
    • Notification: fire a test system notification.
    • Reload application: reload the current application.
    • Take screenshot: take a screenshot and save it in a screenshots directory in your default image location, for example [HOME-FOLDER]/Pictures/screenshots on a Mac.
    • Import workload: pushes large workloads to certain apps, for stress testing, for example sending 2000 contacts to the contacts app, or sending 2000 messages to the email app.
       

Revision Source

<div class="summary">
 <p><span class="seoSummary">This article runs through in detail how to run the Gaia codebase locally, and what tools are available in this setup.</span></p>
</div>
<p>To start with, we should point out that you DON'T have to build Gecko, or B2G, to contribute to Gaia. You just need to download the Gaia source code and have the ability to run and edit it in some way.<br />
 <br />
 There are several different ways to run Gaia:</p>
<ul>
 <li>Flash your phone with an updated Gaia build.</li>
 <li>Launch your Gaia inside a B2G Desktop build.</li>
 <li>Run your Gaia inside the App Manager/Firefox Simulator.</li>
 <li>Launch Gaia inside Desktop Firefox (Nightly is recommended).</li>
</ul>
<p>You can find concise information on running it in these different ways on our <a href="/en-US/Firefox_OS/Developing_Gaia/Different_ways_to_run_Gaia">Different ways to run Gaia</a> page, along with links to more detailed information as required. In general these are ordered from most complex (but most realistic experience provided) to easiest (but least realistic).</p>
<p>In this article we'll be concentrating on running Gaia inside Desktop Firefox — for most changes you'll want to make to the Gaia codebase, this offers the quickest mechanism for testing updates, but obviously there are some features (such as testing device APIs or interaction with phone hardware) that will need a real device.</p>
<div class="note">
 <p><strong>Note</strong>: To get further help with Gaia, the best places to go are the #gaia IRC channel (see <a href="https://wiki.mozilla.org/IRC">Mozilla IRC</a> for more information) and the <a href="https://lists.mozilla.org/listinfo/dev-gaia">dev-gaia mailing list</a>.</p>
</div>
<h2 id="Running_Gaia_in_Desktop_Firefox">Running Gaia in Desktop Firefox</h2>
<ol>
 <li>First, make a fork of the main <a href="https://github.com/mozilla-b2g/gaia">Gaia repo on Github</a>.</li>
 <li>Next, clone your fork locally:
  <pre class="brush: bash">
git clone https://github.com/your-username/gaia.git</pre>
 </li>
 <li>Add the upstream like this:
  <pre class="brush: bash">
cd gaia
git remote add upstream https://github.com/mozilla-b2g/gaia</pre>
 </li>
 <li>Next, install the <a href="http://www.fontsquirrel.com/fonts/fira-sans">Fira Sans font</a> on your system: this is the font Gaia uses on real devices, so it is useful to have it available to use when running Gaia on desktop too, especially when you are trying to debug issues related to overflow or font-sizing, for example.</li>
 <li>Now you need to create a debug profile of Gaia. Running <code>DEBUG=1 make</code> inside your repo folder creates a profile in the <code>profile-debug</code> directory, which is setup for optimal debugging. It creates unpackaged (hosted versions) of the Gaia apps that can be served directly via the local HTTPD server bundled along with Firefox desktop as an extension. When you make a change you just need to refresh your browser window to see the result (as you'll see later), rather than having to rebuild the profile, repush it to the device, etc. This is really good for rapid CSS/JS/HTML hacking.</li>
 <li>With your debug profile built, run it in your desktop Firefox build (we'd recommend you use <a href="http://nightly.mozilla.org/">Firefox Nightly</a>) from the command line, using a command with the following structure:
  <pre class="brush: bash">
/path/to/firefoxnightly -profile /path/to/B2G/gaia/profile-debug -no-remote</pre>
  For example, on OS X, we ran the following command:
  <pre class="brush: bash">
/Applications/FirefoxNightly.app/Contents/MacOS/firefox -profile /Users/bob/git/gaia/profile-debug -no-remote</pre>
 </li>
</ol>
<p>This should load up your Gaia profile running in a desktop Firefox tab, like so (you'll notice that the URL is <code>http://system.gaiamobile.org:8080/</code>):</p>
<p><img alt="A screenshot of Firefox OS Gaia being run inside a desktop Firefox nightly build." src="https://mdn.mozillademos.org/files/7925/gaia-desktop-smaller.png" style="width: 640px; height: 495px; margin: 0px auto; display: block;" /></p>
<div class="note">
 <p><strong>Note</strong>: If you open a tab in the Firefox desktop window Gaia is running in, enter <code>about:config</code>, and search for "gaia", you'll find a number of <code>extensions.gaia.*</code> prefs — which the <code>httpd.js</code> extension is using. You'll also be able to find the <code>network.dns.localDomains</code> pref, which is the trick that makes <code>http://system.gaiamobile.org:8080</code> connect on your localhost.</p>
</div>
<div class="note">
 <p><strong>Note</strong>: The <code>make</code> command is run inside the Gaia directory to create a profile (including apps, setting, etc.) that can be loaded on a phone, run inside an emulator, etc. The <code>make</code> command has a <a href="/en-US/Firefox_OS/Developing_Gaia/make_options_reference">number of options</a> to create different kinds of build. Just running <code>make</code> creates a standard production profile inside gaia/make, with packaged apps, which is not set up for optimum modification and debugging.</p>
</div>
<h2 id="Available_tools">Available tools</h2>
<p>You'll see that this view has a number of different tools available, including:</p>
<ul>
 <li>Responsive design view in the top left corner.</li>
 <li>All the standard Firefox Toolbox debugging tools available to the right of the screen (by default; this can be moved to the bottom of the screen if you like, but on the right makes more sense when debugging the small screen display on the left.)</li>
 <li>A special Firefox OS tools tab on the toolbox that provides some specific tools for debugging Firefox OS in this mode:
  <ul>
   <li><strong>Notification</strong>: fire a test system notification.</li>
   <li><strong>Reload application</strong>: reload the current application.</li>
   <li><strong>Take screenshot</strong>: take a screenshot and save it in a screenshots directory in your default image location, for example <code>[HOME-FOLDER]/Pictures/screenshots</code> on a Mac.</li>
   <li><strong>Import workload</strong>: pushes large workloads to certain apps, for stress testing, for example sending 2000 contacts to the contacts app, or sending 2000 messages to the email app.<br />
    &nbsp;</li>
  </ul>
 </li>
</ul>
Revert to this revision