|
|
| (121 intermediate revisions by 39 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
| |
| | |
| === Pull and apply Marionette patches ===
| |
| | |
| These patches should land in mozilla-central soon, and this step will not be required.
| |
| | |
| Follow the instructions here:
| |
| | |
| https://developer.mozilla.org/en/Marionette/Setup#Running_Marionette_on_Desktop_Firefox_or_B2G_Desktop_builds
| |
| | |
| === 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).
| |
| | |
| ==== Mac ====
| |
| | |
| Build will fail on checking phase and complains about g++ and gcc executable not found. Please do the following first:
| |
| | |
| sudo ln -s /Developer/usr/bin/gcc /Developer/usr/bin/gcc-4.2
| |
| sudo ln -s /Developer/usr/bin/g++ /Developer/usr/bin/g++-4.2
| |
| | |
| == Running B2G ==
| |
| | |
| === 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.
| |
| | |
| == 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 two lines of /etc/apache2/sites-available/default 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>
| |
| | |
| 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.
| |
| | |
| 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.
| |
| | |
| | |
| 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 edit the ${PROFILE}/prefs.js file while the B2G application is closed (this is important if you don't want your changes to be overwritten) and add lines like:
| |
| | |
| user_pref(my.pref.name, true);
| |
| | |
| First go to {{MDN|Setting_up_extension_development_environment#Development_preferences|MDC development preferences}} and set up the preferences declared there.
| |
| | |
| 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'''.
| |