|
|
| (106 intermediate revisions by 37 users not shown) |
| Line 1: |
Line 1: |
| Inside Gaia everything is a Web Application, see {{MDN|Apps|Apps on MDN}}.
| | #REDIRECT [[mdn:Firefox OS/Developing Gaia]] |
| | |
| When Gaia starts, the homescreen application is the first application displayed on the screen.
| |
| | |
| The homescreen application reads all installed web applications and shows an icon for each. This is done by using the window.navigator.mozApps object that exposes the Application Registry API [http://mxr.mozilla.org/mozilla-central/source/dom/interfaces/apps/nsIDOMApplicationRegistry.idl].
| |
| | |
| Gaia can be run in 3 different ways, each one requiring some specific steps to be set-up:
| |
| | |
| * inside a web browser such a Firefox
| |
| * inside a device emulator
| |
| * on the device
| |
| | |
| Throughout these instructions the following is assumed:
| |
| | |
| GAIA = PATH_TO_GAIA_REPOSITORY
| |
|
| |
| DOMAIN_NAME = gaiamobile.org
| |
|
| |
| PROFILE = PATH_TO_PROFILE
| |
| | |
| == Building B2G ==
| |
| | |
| === Pull the code ===
| |
| hg clone http://hg.mozilla.org/mozilla-central src
| |
| git clone https://github.com/andreasgal/gaia gaia
| |
| | |
| === Create a mozconfig ===
| |
| Create a file named "mozconfig" in the mozilla-central directory.
| |
| Here's an example mozconfig.
| |
| | |
| 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
| |
| ac_add_options --enable-b2g-ril
| |
| | |
| # turn on marionette
| |
| ac_add_options --enable-marionette
| |
| | |
| === Add user.js to profile ===
| |
| | |
| Find the profile folder:
| |
| | |
| http://kb.mozillazine.org/Profile_folder_-_Firefox#Navigating_to_the_profile_folder
| |
| | |
| Replace "Firefox" with "B2G" to find the B2G profile folder. Inside the default profile, create a file user.js with:
| |
| | |
| pref("marionette.defaultPrefs.enabled", true);
| |
| pref("b2g.remote-js.enabled", true);
| |
| pref("b2g.remote-js.port", 4242);
| |
| pref("javascript.options.showInConsole", true);
| |
| pref("nglayout.debug.disable_xul_cache", true);
| |
| pref("browser.dom.window.dump.enabled", true);
| |
| pref("javascript.options.strict", true);
| |
| pref("dom.report_all_js_exceptions", true);
| |
| pref("nglayout.debug.disable_xul_fastload", true);
| |
| | |
| Marionette will listen on port 2828, and if you include the remote-js.enabled and port lines, you will be able to telnet to localhost 4242 (or whatever port you desire) to get an interactive javascript REPL.
| |
| | |
| === Build ===
| |
| In the mozilla-central directory:
| |
| | |
| make -f client.mk build
| |
| | |
| The build will appear in ../build (or whatever MOZ_OBJDIR is set to in your mozconfig).
| |
| | |
| == Running B2G ==
| |
| | |
| NOTE: section is out of date and can be safely skipped.
| |
| | |
| === Desktop ===
| |
| | |
| declare -x B2G_HOMESCREEN=file://${GAIA}/homescreen.html
| |
| ../build/dist/bin/b2g
| |
| | |
| You may want to add the $MOZ_OBJDIR/dist/bin directory to your shell's $PATH and B2G_HOMESCREEN to your shell environment so you can just type "b2g" anywhere.
| |
| | |
| ==== Mac ====
| |
| | |
| For Mac users, please run
| |
| | |
| ../build/dist/B2G.app/Contents/MacOS/b2g
| |
| | |
| instead. In ./bin/b2g all the keyboard/mouse event will be redirect to Terminal for unknown reason.
| |
| | |
| == Create B2G Profile at the Specified Location ==
| |
| | |
| The B2G profile can be create at the specific location. To do that execute b2g with following arguments:
| |
| | |
| ../build/dist/bin/b2g -ProfileManager
| |
| | |
| On the Choose User Profile screen, the default profile can be removed and a new profile can be created at the specified location.
| |
| | |
| == 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:
| |
| | |
| 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 the b2g application ==
| |
| To reload/restart b2g everything simply enter the command:
| |
| adb shell killall b2g
| |
| | |
| == Running tests ==
| |
| There is a dedicated test framework for B2G called [https://developer.mozilla.org/en/Marionette Marionette]. You can set up Marionette with [https://developer.mozilla.org/en/Marionette/Setup#Running_Marionette_on_Desktop_Firefox_or_B2G_Desktop_builds B2G Desktop] or for [https://developer.mozilla.org/en/Marionette/Setup#Running_B2G_and_Marionette_on_an_emulator_or_device an emulator or device].
| |
| | |
| === Desktop ===
| |
| If you are running a desktop build you can also write browser-chrome tests.
| |
| | |
| ==== Running tests ====
| |
| Be sure to have MOZ_OBJDIR define in your shell environment.
| |
| MOZ_OBJDIR should point to your b2g desktop build directory - the one specified in the .mozconfig file.
| |
| | |
| cd $GAIA
| |
| MOZ_OBJDIR=PATH/TO/THE/BUILD/DIR make mochitest
| |
| | |
| The desktop build of b2g should be lanched with a new window containing the result of the tests run.
| |
| | |
| ==== Caveat ====
| |
| The test tools will be looking for an executable at path
| |
| | |
| $MOZ_OBJDIR/dist/B2G.app/Contents/MacOS/b2g-bin
| |
| on a mac, or
| |
| $MOZ_OBJDIR/dist/bin/b2g-bin
| |
| on linux
| |
| | |
| Which isn't generated by the build. So you'll have to symlink your b2g binary to b2g''-bin''.
| |
| | |
| cd $MOZ_OBJDIR/dist/B2G.app/Contents/MacOS
| |
| # or
| |
| cd $MOZ_OBJDIR/dist/bin
| |
|
| |
| ln -s b2g b2g-bin
| |
| | |
| Also in order to run the mozTelphony related tests make sure that the prefs in your ''b2g/app/b2g.js'' refers to
| |
| | |
| http://localhost:7777/apps/dialer/dialer.html
| |
| | |
| And not something with ''/data/local/apps/''
| |
| | |
| ==== Writing tests ====
| |
| For more information about Mochitest, please refer to {{MDN|Mochitest#Test_functions}}
| |
| | |
| For more information about browser-chrome tests, please refer to {{MDN|Browser_chrome_tests}}
| |
| | |
| New browser-chrome tests should be put directly in the $GAIA/tests/ directory.
| |
| There is already a few of them there that you can look at to have a better idea about how to write yours!
| |
| | |
| == Hosting Gaia on your own machine ==
| |
| | |
| For development you might find it helpful to host Gaia apps on your own machine. Below is a quick guide on how to set that up, this is based on Ubuntu but should work on other platforms with a few modifications.
| |
| | |
| === Set up Apache ===
| |
| | |
| If you haven't already installed Apache, you should install it:
| |
| $ sudo apt-get install apache2
| |
| | |
| Enable virtual hosts by changing the first line of '''/etc/apache2/sites-available/default''' from:
| |
| <VirtualHost *:80>
| |
| | |
| to:
| |
| NameVirtualHost *
| |
| <VirtualHost *>
| |
| | |
| Create a virtual host config at '''/etc/apache2/sites-available/gaiamobile.org''':
| |
| | |
| # Redirect [browser|sms|...].gaiamobile.org to ${GAIA}/apps/[browser|sms|...]/.
| |
| <VirtualHost *>
| |
| ServerName homescreen.gaiamobile.org
| |
| ServerAlias *.gaiamobile.org
| |
| VirtualDocumentRoot /path/to/gaia/apps/%1/
| |
| </VirtualHost>
| |
|
| |
| <VirtualHost *>
| |
| ServerName gaiamobile.org
| |
| ServerAlias gaiamobile.org
| |
| DocumentRoot /path/to/gaia
| |
| </VirtualHost>
| |
|
| |
| # Add the correct mimetypes for offline cache manifest
| |
| AddType text/cache-manifest .appcache
| |
|
| |
| # Prevent Apache from caching apps files
| |
| <IfModule mod_expires.c>
| |
| ExpiresActive on
| |
| ExpiresDefault "access plus 0 hours"
| |
| ExpiresByType text/html "access plus 0 hours"
| |
| ExpiresByType text/xml "access plus 0 hours"
| |
| ExpiresByType text/css "access plus 0 hours"
| |
| ExpiresByType text/plain "access plus 0 hours"
| |
| ExpiresByType application/x-javascript "access plus 0 hours"
| |
| ExpiresByType application/javascript "access plus 0 hours"
| |
| ExpiresByType text/javascript "access plus 0 hours"
| |
| ExpiresByType text/cache-manifest "access plus 0 hours"
| |
| ExpiresByType image/gif "access plus 0 hours"
| |
| ExpiresByType image/png "access plus 0 hours"
| |
| ExpiresByType image/jpeg "access plus 0 hours"
| |
| ExpiresByType image/x-icon "access plus 0 hours"
| |
| </IfModule>
| |
| | |
| '''Note:''' the "ExpiresByType" rules will prevent Apache from caching. Make sure you have properly disabled the cache on your client (i.e. browser.cache.offline.enable should be set to false, as mentioned at the end of this document).
| |
| | |
| Enable the Apache modules
| |
| $ sudo a2enmod expires
| |
| $ sudo a2enmod vhost_alias
| |
| | |
| Enable the gaiamobile.org virtual host
| |
| $ sudo a2ensite gaiamobile.org
| |
| | |
| Restart Apache
| |
| $ sudo apache2ctl graceful
| |
| | |
| === Point gaiamobile.org at your machine ===
| |
| Edit '''/etc/hosts''' (or [http://en.wikipedia.org/wiki/Hosts_%28file%29#Location_in_the_file_system somewhere else] on other systems) and add the following line
| |
| | |
| 127.0.0.1 gaiamobile.org dialer.gaiamobile.org sms.gaiamobile.org browser.gaiamobile.org maps.gaiamobile.org camera.gaiamobile.org gallery.gaiamobile.org video.gaiamobile.org market.gaiamobile.org music.gaiamobile.org settings.gaiamobile.org clock.gaiamobile.org crystalskull.gaiamobile.org penguinpop.gaiamobile.org towerjelly.gaiamobile.org wikipedia.gaiamobile.org cnn.gaiamobile.org bbc.gaiamobile.org nytimes.gaiamobile.org calculator.gaiamobile.org
| |
| | |
| '''Note:''' not all of these are required any more, needs updating.
| |
| | |
| Now you should be able to point your web browser at homescreen.gaiamobile.org and get the homscreen.
| |
| | |
| === Configure your device to load Gaia from your development machine ===
| |
| Pull the hosts file from the device
| |
| | |
| $ adb pull /system/etc/hosts
| |
| | |
| add the line to the hosts file
| |
| | |
| 192.168.1.3 gaiamobile.org dialer.gaiamobile.org sms.gaiamobile.org browser.gaiamobile.org maps.gaiamobile.org camera.gaiamobile.org gallery.gaiamobile.org video.gaiamobile.org market.gaiamobile.org music.gaiamobile.org settings.gaiamobile.org clock.gaiamobile.org crystalskull.gaiamobile.org penguinpop.gaiamobile.org towerjelly.gaiamobile.org wikipedia.gaiamobile.org cnn.gaiamobile.org bbc.gaiamobile.org nytimes.gaiamobile.org calculator.gaiamobile.org
| |
| | |
| (where 192.168.1.3 is the static IP of your development box on your network)
| |
| | |
| '''Note:''' not all of these are required any more, needs updating.
| |
| | |
| Push the hosts file back to the device
| |
| adb push hosts /system/etc/hosts
| |
| | |
| Reboot the device and if Wifi is configured it should load the homescreen from your desktop machine!
| |
| | |
| == Tell B2G which Web Applications are installed (aka avoid the empty homescreen) ==
| |
| At this point B2G should startwith an empty homescreen.
| |
| | |
| | |
| In order for B2G to know which applications are available on your system you need to declare them in the profile folder of B2G.
| |
| | |
| All the necessary files live in ${GAIA}/profile/webapps so the only thing you need to do is to make a link between this folder and ${PROFILE}/webapps.
| |
| | |
| To generate the ${GAIA}/profile/webapps and ${GAIA}/profile/OfflineCache folders, execute:
| |
| | |
| make -C ${GAIA} copy-manifests
| |
| make -C ${GAIA} offline
| |
| | |
| First locate your profile folder [http://support.mozilla.com/en-US/kb/Profiles] and then execute the following lines:
| |
| | |
| ln -s ${GAIA}/profile/webapps ${PROFILE}/webapps
| |
| ln -s ${GAIA}/profile/OfflineCache ${PROFILE}/OfflineCache
| |
| | |
| |ln| is the standard way to make link on unix/linux systems. The method of creating such a link can vary depending on your system, see [http://en.wikipedia.org/wiki/Symbolic_link] for help.
| |
| | |
| The homescreen can be pointed to http://homescreen.gaiamobile.org/:
| |
| declare -x B2G_HOMESCREEN=http://homescreen.gaiamobile.org/
| |
| | |
| Restart B2G
| |
| ../build/dist/bin/b2g
| |
| | |
| == Tips ==
| |
| | |
| === Preferences ===
| |
| There are many preferences used in B2G. Here are the most useful ones you need to know while hacking on top of it.
| |
| | |
| There is no about:config page in B2G so you will need to create or edit the ${PROFILE}/user.js file and add lines like:
| |
| | |
| user_pref(my.pref.name, true);
| |
| | |
| Further up this page, in the section https://wiki.mozilla.org/Gaia/Hacking#Add_user.js_to_profile there is a user.js file which will set many useful debugging preferences. Many of these are from here: {{MDN|Setting_up_extension_development_environment#Development_preferences|MDC development preferences}}.
| |
| | |
| If you want to disable the offline cache use:
| |
| user_pref('browser.cache.offline.enable', false);
| |
| | |
| === Javascript Console ===
| |
| You can open the Javascript Console by running:
| |
| ../build/dist/bin/b2g -jsconsole
| |
| | |
| === Touch events ===
| |
| To enable the necessary interfaces in the Firefox web browser you need to go to about:config and add the boolean preference '''dom.w3c_touch_events.enabled''' and set it to '''true'''.
| |