Understanding the Gaia codebase

Before you start to make your own changes to the Gaia codebase, you should understand the basics of how it is all structured, and what coding conventions are used. This article covers both of these points.

Gaia branches

There are many different branches in the Gaia codebase, and depending on what work you are doing (or what device you have) you might not just want to download, hack and make the master branch. Here is a brief guide to the most common repos you'll likely be interested in:

master — the latest development branch. You'll want to use this branch if you are developing (or fixing bugs on) new features, or you want to run the latest Gaia on your phone or emulator
v2.1, v2.0, v1.4, etc. — feature freeze versions of Gaia 2.1, 2.0, 1.4, etc. You'll want to use these branches if you are fixing a bug in a specific Gaia version, or want to develop an app and make sure it supports a specific Gaia version (for example, you might be using the Firefox OS Building Blocks with modifications, and want to make sure your layout still works across different Gaia versions.)
v1.3t — the low-memory version of Gaia, developed for running on low-memory devices such as the Tarako or Spice Fire One. If you want to develop an app for such devices, this is the branch you should work with.

Gaia codebase structure

The following section outlines all the most important parts of the Gaia codebase.

apps/

This directory contains all of the main Gaia apps, both apps shown in the homescreen — such as calendar and camera — and underlying apps — such as system, homescreen, and keyboard.

The apps work in slightly different ways, but all have a number of common features, including:

index.html: the central file for each app
manifest.webapp: the manifest file defines the app
locales: localisation strings for that app
test: unit and integration tests particular to that app
js, style: scripts and styles for that app
resources: images, sounds and other assets

Note: You can find more information about the apps actually work on our Gaia apps guide.

build/

This directory contains build scripts.

dev_apps/

This directory contains other apps that are included by customization. For example you could include custom apps that you want to include in custom builds in here.

Note: For more information about Gaia customization, read our Market customizations guide.

keyboard/

The keyboard directory contains keyboard dictionaries and layouts for different languages.

locales/

This directory contains a JSON file, languages_all.json, which defines what languages are supported on Gaia. For more insight into how apps are localized, read Getting started with app localization.

shared/

This directory contains a number of resources that multiple apps make use of; the most notable parts of these are:

gaia/shared/js: JavaScript libraries that perform common functions
l10n.js: A localisation library that detects your device's locale, and replaces localisable strings in your apps with the strings found in the apps locales folders. Localisable strings to be replaced are contained in elements with data-l10n-id attributes.
gaia/shared/locales: Localised resources for different locales.
gaia/shared/resources: Common assets such as icons, ringtones and alarm sound tracks.
gaia/shared/style: stylesheets and other styling resources for common building blocks such as buttons, progress bars, toolbars, tabs, etc. For more information on these, see Firefox OS Building Blocks.
gaia/shared/style_unstable: unstable or experimental styling resources.
gaia/shared/test: JavaScript to define integration and unit tests.

tools/

The tools directory contains tools for build scripts and tests.

Gaia coding style

Gaia follows the Google JavaScript coding style.

Background information:

Coding Style: General practices
Coding Style: JavaScript practices
Coding Style: Naming and formatting code

Specific rules

Make sure HTML files are declared with <!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.

Use expanded conditional structures:

Bad
if (expression) doSomething();
Correct
if (expression) {
  doSomething();
}

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

Per commit coding style check

Gaia uses jshint to automatically check JS coding styles before each commit (via a git pre-commit hook). Once you submit a Pull Request to the Gaia repository, the Travis (Github Continuous Integration) server will run this linter to double check all styles are right.

The precommit hook script is in gaia/tools/pre-commit and will be copied to project's .git/hooks folder once a make command is executed.

Note: We used to use gjslint to check coding styles, but we have since deprecated its use as jshint is stricter and produces better results. We’ve been using JSHint since Firefox OS 1.4, and gjslint is now only recommended for legacy files that have not yet been moved to JSHint.

Running linting checks manually via Gaia

Before submitting a patch we recommend you run JSHint on it manually to check for any style errors.

You should look in the gaia/build/jshint directory for more details about jshint in Gaia; Gaia provides the build script for you. You can run:

$ make lint

to automatically run both the gjslint and jshint style checks. Or you can run

$ make hint

to just run the jshint style check.

$ make eslint

to just run the eslint style check.

Note: If you want to install jshint yourself, without using Gaia, you can use the following:

npm install jshint -g
jshint myfile.js