|
|
| (9 intermediate revisions by 9 users not shown) |
| Line 1: |
Line 1: |
| '''Note:''' This page is soon migrating to [https://developer.mozilla.org/en-US/docs/Mozilla/Firefox_OS/Gaia/Hacking MDN]. Please contribute your changes there.
| | #REDIRECT [[mdn:Firefox OS/Developing Gaia]] |
| | |
| Gaia is the collection of [https://developer.mozilla.org/apps web apps] which make up the front end of [http://www.mozilla.org/firefoxos/ Firefox OS] (codenamed [https://wiki.mozilla.org/B2G Boot to Gecko]).
| |
| | |
| Everything you see on the screen in Firefox OS is built using open web technologies, including the homescreen and dialer.
| |
| | |
| You can get started hacking on Gaia with nothing more than a web browser and a text editor, so what are you waiting for?
| |
| | |
| == Running Gaia Apps ==
| |
| | |
| There are two ways to run Gaia apps:
| |
| | |
| * B2G Desktop
| |
| * B2G on a device
| |
| | |
| === B2G Desktop ===
| |
| | |
| B2G Desktop is a desktop build of the B2G app runtime used on devices where all apps should run as they would on a device, including the homesreen.
| |
| | |
| === Aurora Builds (v1 everyone should use this) ===
| |
| | |
| You can download an Aurora build of B2G Desktop from [http://ftp.mozilla.org/pub/mozilla.org/b2g/nightly/latest-mozilla-aurora/ http://ftp.mozilla.org/pub/mozilla.org/b2g/nightly/latest-mozilla-aurora/] for Linux, OS X and Windows.
| |
| | |
| Aurora/Nightly builds include gaia by default, and they should just run out of the box. This is done by using a wrapper program. When a profile is bundled with the nightly build (GAIADIR specified in the mozconfig), the binary 'b2g' is a wrapper program and 'b2g-bin' is the actual b2g binary.
| |
| | |
| If you want to modify Gaia, you will need to separately clone and "build" Gaia:
| |
| | |
| $ git clone git://github.com/mozilla-b2g/gaia.git gaia
| |
| $ cd gaia
| |
| $ DEBUG=1 make
| |
| | |
| Then you just run with B2G Desktop instead of Firefox. The nightlies produced for TBPL use 'b2g-bin'. If you build a desktop build yourself without specifying "GAIADIR=/path/to/gaia/repo" in your mozconfig, use 'b2g':
| |
| | |
| $ /path/to/b2g-bin -profile /path/to/gaia/profile
| |
| | |
| On OSX, the b2g-bin will be in the B2G.app package contents, so the path is a little different:
| |
| | |
| $ /path/to/b2g/B2G.app/Contents/MacOS/b2g-bin -profile /path/to/gaia/profile
| |
| | |
| To update gaia you run the following command inside the Gaia directory:
| |
| | |
| $ git pull
| |
| | |
| (or "git fetch && git merge upstream/master" if you checked out from your own clone).
| |
| | |
| === Gaia Version 2 ===
| |
| | |
| Use the below builds for work on version 2 of Gaia.
| |
| | |
| You can download a nightly build of B2G Desktop from [http://ftp.mozilla.org/pub/mozilla.org/b2g/nightly/latest-mozilla-central/ http://ftp.mozilla.org/pub/mozilla.org/b2g/nightly/latest-mozilla-central/] for Linux, OS X and Windows.
| |
| | |
| ==== Build Your Own ====
| |
| | |
| If you prefer you can build B2G Desktop yourself by checking it out from mozilla-central using Mercurial:
| |
| | |
| $ hg clone http://hg.mozilla.org/mozilla-central src
| |
| | |
| Before building, make sure you have the correct [https://developer.mozilla.org/en-US/docs/Developer_Guide/Build_Instructions#Build_prerequisites build prerequisites] to build mozilla-central for your platform. After that, create a file called .mozconfig in your source tree to configure some options. Here's an example:
| |
| | |
| mk_add_options MOZ_OBJDIR=../build
| |
| mk_add_options MOZ_MAKE_FLAGS="-j9 -s"
| |
|
| |
| ac_add_options --enable-application=b2g
| |
| ac_add_options --disable-libjpeg-turbo
| |
|
| |
| # This option is required if you want to be able to run Gaia's tests
| |
| ac_add_options --enable-tests
| |
|
| |
| # turn on mozTelephony/mozSms interfaces
| |
| # Only turn this line on if you actually have a dev phone
| |
| # you want to forward to. If you get crashes at startup,
| |
| # make sure this line is commented.
| |
| #ac_add_options --enable-b2g-ril
| |
| | |
| If you'd like to build with a packaged profile and include the b2g wrapper script, you can add the following to your mozconfig (with correct path):
| |
|
| |
| GAIADIR=/path/to/gaia/repo
| |
| | |
| Then run make inside the mozilla-central directory:
| |
| | |
| $ make -f client.mk build
| |
| | |
| '''Note:''' Ensure you're using python2 and not python3 as the build will fail with python3.
| |
| | |
| The build will appear in ../build (or whatever MOZ_OBJDIR is set to in your .mozconfig) and will take a ''long'' time the first time you build.
| |
| | |
| On Linux, once it's built you can run B2G with:
| |
| | |
| # if you specified GAIADIR (e.g. Mozilla Nightlies)
| |
| $ ../build/dist/bin/b2g-bin -profile /path/to/gaia/profile
| |
|
| |
| # if you did not specify GAIADIR
| |
| $ ../build/dist/bin/b2g -profile /path/to/gaia/profile
| |
| | |
| (substituting /path/to/gaia with the path to which you cloned Gaia).
| |
| | |
| On OSX, once it's built, you can run B2G with:
| |
| | |
| # if you specified GAIADIR (e.g. Mozilla Nightlies)
| |
| $ ../build/dist/B2G.app/Contents/MacOS/b2g-bin -profile /path/to/gaia/profile
| |
|
| |
| # if you did not specify GAIADIR
| |
| $ ../build/dist/B2G.app/Contents/MacOS/b2g -profile /path/to/gaia/profile
| |
| | |
| When you want to update your own B2G Desktop build do:
| |
| | |
| $ hg pull && hg update
| |
| $ make -C ../build/b2g
| |
| | |
| In the gaia directory:
| |
| | |
| $ git pull
| |
| | |
| ==== Simulating Hardware Buttons ====
| |
| | |
| On a desktop B2G build, you don't have access to hardware buttons, but you can simulate them:
| |
| | |
| * Home button: fn + left arrow (OS X)
| |
| * Power button: fn + right arrow (OS X)
| |
| * Volume button: fn + up/down arrows (OS X)
| |
| * open Cards View: cmd + fn + left arrow (OS X)
| |
| | |
| === B2G on a device ===
| |
| | |
| It is possible to build & run Firefox OS on a limited number of smartphones. Please see [https://github.com/mozilla-b2g/B2G/blob/master/README.md documentation here].
| |
| | |
| There is also [https://wiki.mozilla.org/B2G/DeveloperPhone#Gaia.2FB2G_Development_Environment documentation here] about testing changes on your device.
| |
| | |
| == Unit Tests ==
| |
| | |
| Gaia comes with a suite of unit tests, which you can run using the built-in Test Agent app (by running it in B2G desktop, B2G on a device, or by navigating to http://test-agent.gaiamobile.org:8080 in Firefox Nightly).
| |
| | |
| See [https://developer.mozilla.org/en-US/docs/Mozilla/Boot_to_Gecko/Gaia_Unit_Tests here] for more information on writing and running unit tests for Gaia.
| |
| | |
| == Filing Bugs ==
| |
| Bugs are filed on Bugzilla under [https://bugzilla.mozilla.org/buglist.cgi?product=Boot2Gecko&component=Gaia&resolution=--- Boot2Gecko > Gaia].
| |
| | |
| File a new bug under the Gaia component (or one of the sub-components) [https://bugzilla.mozilla.org/enter_bug.cgi?product=Boot2Gecko here]
| |
| | |
| == Contributing Code ==
| |
| | |
| 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:
| |
| * [https://bugzilla.mozilla.org/buglist.cgi?quicksearch=component:gaia%20sw:polish%20@nobody;list_id=4566236 Unowned Gaia polish bugs on Bugzilla]
| |
| * [http://www.joshmatthews.net/bugsahoy/?b2g=1 Mentored bugs]
| |
| | |
| === Submitting a Patch ===
| |
| * Assign an un-owned Gaia bug to yourself on [https://bugzilla.mozilla.org/buglist.cgi?product=Boot2Gecko&component=Gaia&resolution=--- Bugzilla] (you'll need a Bugzilla account).
| |
| * Fork [https://github.com/mozilla-b2g/gaia Gaia on Github] (you'll need a GitHub account) and clone your fork
| |
| $ git clone https://github.com/USERNAME/gaia.git gaia
| |
| * Develop in a branch on your fork (remembering to keep to the [https://wiki.mozilla.org/Gaia/Hacking#Coding_Style Coding Style guidelines] for Gaia)
| |
| $ git branch BRANCHNAME
| |
| $ git checkout BRANCHNAME
| |
| * Commit your changes
| |
| $ git add /FILE/TO/ADD
| |
| $ git commit -m "COMMIT MESSAGE INCLUDING BUG NUMBER"
| |
| * Push to 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
| |
| * Paste a link to the pull request in the bug on Bugzilla
| |
| * Your patch will be reviewed on Github (if it isn't getting reviewed try asking around on IRC or the mailing list or commenting on the bug)
| |
| * To make changes in response to the code review, just push more commits to the same branch and your pull request will get updated automatically
| |
| $ git add /FILE/TO/ADD
| |
| $ git commit -m "COMMIT MESSAGE"
| |
| $ git push
| |
| | |
| (ideally squash all your changes into a single commit using git rebase)
| |
| | |
| * Once the reviewer is happy with your patch, they will merge it into the master branch for you
| |
| | |
| (ideally the commit message should have r=REVIEWER_NAME added to the commit message of a the squashed commit and your patch includes a passing unit test)
| |
| | |
| === Reviewers ===
| |
| | |
| Gaia now has module owners and peers! For code reviews, ask any of the peers listed [https://wiki.mozilla.org/Modules/Boot2Gecko here].
| |
| | |
| === Coding Style ===
| |
| * Background:
| |
| ** [[MDC:Developer Guide/Coding Style#General practices]]
| |
| ** [[MDC:Developer Guide/Coding Style#JavaScript practices]]
| |
| ** [[MDC:Developer Guide/Coding Style#Naming and Formatting code]]
| |
| | |
| * make sure HTML files are declared <!DOCTYPE html> (i.e., HTML5). IE9+ will load them in compatibility mode otherwise.
| |
| | |
| * add a <code>"use strict";</code> statement (exactly that!) to the top of your JS files
| |
| | |
| * 2 spaces for indentation - do not use tab.
| |
| | |
| * Line break are free (I promise) don't hesitate to use them to separate logical block inside your functions.
| |
| | |
| * Files are named <code>like_this.js</code>.
| |
| | |
| * Use single quote instead of double quotes.
| |
| | |
| * Additional rules:
| |
| Bad:
| |
| if (expression) doSomething();
| |
| | |
| Correct:
| |
| if (expression)
| |
| doSomething();
| |
| | |
| === System app ===
| |
| | |
| See here for some rules.
| |
| https://groups.google.com/d/msg/mozilla.dev.gaia/rEhSrw6XmT4/UNvE7qW9pgYJ
| |
| | |
| === Before submitting a patch ===
| |
| On each javascript files you are adding or you have modified, run:
| |
| gjslint --nojsdoc my_file.js
| |
| | |
| http://code.google.com/closure/utilities/docs/linter_howto.html
| |
| | |
| Set of smoke tests to run before you check-in a patch:
| |
| [[media:PatchSmokeTests.pdf|PatchSmokeTests.pdf]]
| |
| | |
| == Contacting The Team ==
| |
| * [https://lists.mozilla.org/listinfo/dev-gaia Gaia Mailing List]
| |
| * #gaia IRC channel on irc.mozilla.org
| |
| | |
| | |
| == Tips ==
| |
| === Linux B2G Desktop support ===
| |
| | |
| ==== The homescreen is empty ====
| |
| Currently, under Linux, OOP frame aren't rendered properly.
| |
| The homescreen isn't actually rendered here...
| |
| | |
| If you just want to happily hack on pure UI (css and JS) you can safely run with OOP disabled and avoid those issues.
| |
| Change the line in build/settings.py
| |
| | |
| "debug.oop.disabled": False,
| |
| | |
| to
| |
| | |
| "debug.oop.disabled": True,
| |
| | |
| | |
| Then rebuild your profile with
| |
| | |
| $ rm -r profile && make
| |
| | |
| === Port Forwarding ===
| |
| To forward the socket on the phone to the desktop (for desktop development), you first need to get rilproxy to expose it as such, rather than exposing it to Gecko. In the gaia directory:
| |
| | |
| $ make forward
| |
| | |
| This runs the commands:
| |
| $ adb shell touch /data/local/rilproxyd
| |
| $ adb shell killall rilproxy
| |
| $ adb forward tcp:6200 localreserved:rilproxyd
| |
| | |
| The file located at /data/local/rilproxyd will be deleted once the rilproxy daemon will start again. As a consequence you have to do this manipulation every time your device restarts.
| |
| | |
| === Restarting B2G on a device from the desktop ===
| |
| adb shell killall b2g
| |
| | |
| === B2G Desktop JavaScript Console ===
| |
| | |
| You can run B2G Desktop with the JavaScript console by using the -jsconsole flag
| |
| | |
| $ /path/to/b2g-bin -jsconsole
| |
| | |
| === Launching an app directly ===
| |
| | |
| A "--runapp" option has been added to the B2G Desktop command-line to automatically start an application. The system app is loaded and everything happens like normal; this is not like the old trick where we loaded your app instead of the system app.
| |
| | |
| "--runapp" takes an argument that it normalizes by lower-casing and removing dashes and spaces, and then checks the argument against the similarly normalized app names from app manifests. For example, the name of the e-mail app is currently "E-Mail", but "--runapp email" will run it. Partial matching is not supported right now, but you can enhance b2g/chrome/content/runapp.js if your app name is unwieldy.
| |
| | |
| If you invoke "--runapp" without an argument (or an empty argument), the command will print out a list of all the apps it knows about as well as a brief usage message.
| |
| | |
| One important note is that this command disables the lock-screen as part of its magic and does not re-enable it. The assumption is that you won't use this command on a profile where you are testing the lock screen, or will turn it back on manually. Feel free to enhance the command to behave better if this is a problem for you.
| |
| | |
| In summary:
| |
| | |
| ./b2g -profile /path/to/your/gaia/profile --runapp email
| |
| | |
| runs the e-mail app.
| |
| | |
| === reset-gaia and install-gaia make targets ===
| |
| | |
| The reset-gaia and install-gaia make targets can be used interchangeably. reset-gaia will purge all the existing profiles, database before push Gaia from your working directory (new setting database will also be initialized); install-gaia will just push updates of Gaia.
| |
| | |
| === Blank screen when B2G Desktop starts ===
| |
| When you start b2g using b2g -profile $GAIA/profile a blank screen shows up and you see an error Cannot reach app://system.gaiamobile.org. To fix this there are a couple of things you can check
| |
| | |
| * Rebuild the gaia profile using DEBUG=1 make profile in the $GAIA directory
| |
| * Run b2g again
| |
| * If this doesn't fix it, check if there is any other process listening on port 8080. The default profile of gaia starts httpd.js, which listens on port 8080. When running a debug profile, b2g connects to localhost:8080. If some other process is running on port 8080, b2g will fail to display the home screen of gaia
| |
| ** To find out if this is the case, you can enable logging on httpd.js. The httpd.js in the profile resides in this location - $GAIA/profile/extensions/httpd/content/httpd.js. Edit the variable var DEBUG=false; to change the DEBUG to true. Save the file and restart b2g. On the console now, you will be able to view the httpd's logs
| |
| | |
| === Diagnosing OOM problems ===
| |
| | |
| [https://bugzilla.mozilla.org/show_bug.cgi?id=798747#c7 From Cjones]:
| |
| | |
| Another way to diagnose possible OOMs is to open a terminal and run
| |
| | |
| $ watch -n 1 'adb shell b2g-procrank'
| |
| | |
| If you see the "USS" of one of the app processes go up near 100MB and then that process disappear from the process list (accompanied by some sort of visual crash in gaia), then you've almost certainly seen an OOM kill.
| |