This guide provides a very quick easy guide to developing Gaia apps, including running Gaia inside desktop Firefox. This guide assumes that you know HTML5 technologies, have knowledge of MVC patterns and have keen interest in Firefox OS.
Note: It's important to note that this is not a particularly accurate representation of the experience of using Boot to Gecko on a real mobile device. Many hardware interface features don't work, for example, and Firefox nightly builds may be unstable. But it is still a valid way to get some high level testing done.
What do you need?
- First of all you need to have Git installed. If you prefer working in a visual environment, you might also consider installing the Github client (Github for Mac / Github for Windows). Git is essential for updating the code, promoting your changes, and seeing what other developers are working on.
- Next, you need to fork the Mozilla Gaia repository: https://github.com/mozilla-b2g/gaia. After this is done, you should use a terminal to enter the repository (
cd gaia) and then run the
DEBUG=1 makecommand to configure Gaia correctly for debugging.
- After you are done with setting up your workspace, you need to install the Nightly build of Firefox.
- In that Nightly build, you need to have the Firefox Simulator Extension and App Manager Extension. The App Manager extension should be pre-installed in the nightly build, but you'll need to install the Firefox OS simulator.
- You will need to install the ADB helper for debugging on the remote device, AKA your phone.
- You might want to get a Firefox OS phone. It will show you various use information related to the start time of apps, frame rates, etc. Also, once you have the actual OS running on a device, you will be able to easily test all the supported device APIs.
Now that you have the basic workspace setup, lets get to the apps!
Firefox OS's default apps
The default HTML5 apps provided in the Gaia source code are as follows:
- Cost Control
The first app that gets called up when the phone starts is the System app. This app is responsible for opening and managing the Home Screen app. From the Home Screen app, you can call the other apps to perform various functions. For example, the Dialer app gets called up from the Home Screen app when a user clicks on the phone icon. This Dialer app can then call the Contacts app when the user wants to see the list of contacts to dial.
Explore the Apps
The default apps are all contained in folders inside the
gaia/apps/ folder. Each app folder will contain the following components :
manifest.webappfile: To store metadata about the app.
stylefolder: To store CSS files.
localesfolder: To store translated strings for different languages.
- An HTML file: usually (but not limited to)
Some apps may also have:
elementsfolder: To store other views in HTML files.
testfolder: To run the tests related to the application.
resourcesfolder: Contains other resources such as movies, sounds, etc.
If you are experienced in web development, you will aready have all you need to make some modifications to these apps. Get improving.
Fire Up the Apps
After you have made modifications to those applications, you might want to see the changes. You can either see it in the Firefox OS simulator, or on the physical device. To run the modified Gaia apps on the Firefox Simulator, you will have to run the following command.
/path/to/firefoxnightly -profile /Volumes/Mozilla/b2g/B2G/gaia/profile-debug -no-remote
On Mac OS X, for example, you should do:
/Applications/FirefoxNightly.app/Contents/MacOS/firefox -profile /path/to/B2G/gaia/profile-debug -no-remote
-no-remote is needed to prevent reusing a running Firefox instance instead of creating a new one running the custom Gaia profile.
Running modified Gaia on a device takes a little more work. You will have to build all the things starting from B2G, then Gecko, and then Gaia. If you want to do it, then follow the steps on Building Firefox OS. It is a little easier however to just run the modified app itself in the App Manager, as sene below.
Debug the Broken Apps
After you are done building your app, you might want to debug it.
To do so, first of all get the App Manager and your physical device talking to one another, as shown in Using the App Manager.
Select the Contacts app (for example), then click on that debug button in your app section in the App Manager.
This will not only run the app on a device, but it opens up the debug window as well. Test it out by adding console or debug logs.
The following subsections answer some common questions about debugging apps using Gaia on the desktop.
Note: Refer to Hacking gaia for more make options that can be set that are useful for Gaia debugging.
Can I emulate high resolution devices inside the Firefox desktop browser?
- First of all, you can use the command
GAIA_DEV_PIXELS_PER_PX=1.5 DEBUG=1 maketo make sure the images look sharp on qHD and WVGA devices.
- Next, you can change browser density by opening the about:config page in Firefox and setting the
- Last, you can use the Responsive Design View to 320 x 533 px (which is the equivalent CSS pixel dimensions to 480 x 800 device pixels.)