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.
Running Gaia in Desktop Firefox
- First, make a fork of the main Gaia repo on Github.
- Next, clone your fork locally:
git clone https://github.com/your-username/gaia.git
- Add the upstream like this:
cd gaia git remote add upstream https://github.com/mozilla-b2g/gaia
- 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.
- Now you need to create a debug profile of Gaia. Running
DEBUG=1 makeinside your repo folder creates a profile in the
profile-debugdirectory, 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.
- 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-remoteFor 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
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.
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.
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/screenshotson 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.