Aug 29

I’ve spent the last couple of weeks playing around with Mozilla’s Firefox OS (aka Boot to Gecko or B2G) project as part of my research to prototype an Apache Cordova / Adobe PhoneGap implementation for Firefox OS. I’ll be going through the steps that I had to follow to set up my notebook to build Firefox OS and also the steps required to deploy Firefox OS onto a mobile device.

You should have a solid understanding of using Git and some level of comfort with flashing a mobile device before attempting to build & install Firefox OS. Currently Firefox OS can only be built on Linux or Mac OSX. This article will detail the steps that I used to build Firefox OS on Mac OSX; if you require instructions on how to build on Linux or just want more info you can find it on Mozilla’s Boot to Gecko wiki.

Part 1 – Set Up

First you will need to make sure that you have all the necessary software & tools.

  • XCode 4 & XCode Command Line Tools
  • minimum of 20GB of free hard disk space
  • compatible mobile device (Samsung Nexus S, Samsung Galaxy Nexus, Samsung Galaxy S2) with Ice Cream Sandwich (Android 4.0) installed

If you updated your XCode from version 3 to 4 or if you have a Developer folder in your root directory, you will need to rename the Developer folder otherwise you will run into this issue 777831 when running the Firefox OS bootstrap script.

You will need to run the bootstrap script which will check if you have all of the necessary tools for building Firefox OS.

Open the terminal window and type:

curl -fsSL https://raw.github.com/mozilla-b2g/B2G/master/scripts/bootstrap-mac.sh | bash

There are addition steps required if you plan on building for the Samsung Galaxy S2. I used the Samsung Nexus S as my target mobile device. More details on the additional steps required for the Samsung Galaxy S2 or more info regarding setting up your computer for building Firefox OS can be found here.

Part 2 – Get the Firefox OS code

Next you will need to retrieve the code base from GitHub. If you’re planning to simply build & install Firefox OS you can just clone Mozilla’s repository, but if you’re planning to do some development I would strongly suggest that you fork Mozilla’s repo.

In your terminal window, navigate to the folder where you want to place the Firefox OS code and then type:

git clone https://github.com/mozilla-b2g/B2G.git

Once the code has been completely cloned onto your computer, you will need to navigate into the B2G directory and configure the build for your target device. To configure the build you will need to run the config.sh script and specify the device that you wish to target. In my case I used:

./config.sh nexus-s

The list of device name parameters can be found under the “Configuring B2G for your device section” and additional information on retrieving the code or configuring the Firefox OS emulator can be on the Preparing for your first B2G build page.

Part 3 – Building the code

To build the code you simply type the following command in your terminal window:

./build.sh

Based on my experiences with building Firefox OS, building without any additional parameters to the build script failed every time. If the build fails, you can add the following parameters to help pinpoint where the build process failed.

./build.sh -j1 showcommand

The -j1 parameter tells the build script to use only a single core in your computer’s CPU while the showcommand parameter will display logging of the commands being executed in the terminal window.

A few other things that the #B2G IRC channel suggested:

  • clearing the build cache:
    ccache -C
  • explicitly setting the size of the build cache:
    ccache -M --max-size=20G

    Which is used to set the size of the build cache to 20GB (I ended up setting the –max-size=0 which sets the cache size to unlimited).

Eventually I was able to get a successful build after repeatedly updating my local code repository over the span of 4 days. I also had to use the -j2 parameter on the build script after the repository updates for the build to succeed.

./build.sh -j2

If you are able to successfully build Firefox OS; you should see something like this:

More details on building the code can be found on MDN’s Building Boot to Gecko article.

Part 4 – Installing Firefox OS onto a device

To install your build of Firefox OS onto your device you need to use the flash script.

./flash.sh

If your device gets stuck on screen displayed in the image above; then an error most likely occurred during the flashing process.

You can use the following sequence of commands to get a look at the error log.

./run-gdb.sh

Once you see the (gdb) command prompt, use the continue command.

After using the continue command, you should be returned to the (gdb) command prompt where you can then use the backtrace command to get the output of the log.

With the output of the log, you should be able to get help from the #b2g irc on irc.mozilla.org. The best way to get help is to create a www.pastebin.com of your log output and then link to the pastebin when asking for help on the #b2g irc.

If the flashing is successful, you should see the Firefox OS lock screen on your device.

Additional Resources

All documentation regarding Firefox OS can be found on the MDN’s Firefox OS (Boot 2 Gecko) page.

Jul 15

Here are few neat tricks that you can use when messing around with PhoneGap-webOS’s newCard API:

  • have the new card close the parent card
  • close the new card
  • pass data to a the new card

NOTE: passing data to a new card was a trick discovered by Ken Schreihofer, he has a blog post that explains it in detail.

I’ve included his example along with the examples for closing parent card & new card in this example PhoneGap-webOS 1.0.0rc1 app.

In the index.html of the example app, you will need to open up a new card – which will use “child.html” as the source of the new card in this example.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
<!DOCTYPE html>
<html lang="en">
<head>
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
	<title>PhoneGap WebOS</title>	
	<script type="text/javascript" src="phonegap-1.0.0.js"></script>   	
</head>
<body>
<button onclick="navigator.window.newCard('child.html?firstName=herm&lastName=wong');">create new card & pass data to it</button>
<script>                         
document.addEventListener('deviceready', function () {
    // PhoneGap is ready, do all your stuf here
}, false);
</script>
</body>
</html>

Next create the child.html file in the same directory as your index.html file. Make sure that the source matches the code below:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
<!DOCTYPE html>
 
<html lang="en">
<head>
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
	<title>Child Window</title>
 
	<!--
 
	the data passing example is credited to: Ken Schreihofer   
	http://weboscapades.blogspot.com/2011/07/passing-parameters-to-new-card-in.html
 
	-->
 
	<script type="text/javascript">
	    var query = location.href.substring((location.href.indexOf('?')+1), location.href.length);
	    if(location.href.indexOf('?') < 0) query = '';
	    querysplit = query.split('&');
	    query = new Array();
 
	    for(var i = 0; i < querysplit.length; i++){
	        var namevalue = querysplit[i].split('=');
	        namevalue[1] = namevalue[1].replace(/\+/g, ' ');
	        query[namevalue[0]] = unescape(namevalue[1]);
	    }
 
	    window.onload = function(){
	        document.getElementById('firstname').innerHTML = query['firstName'];
	    document.getElementById('lastname').innerHTML = query['lastName'];
	    }
	</script>		
</head>
<body>
	<h1>Who are you?</h1>
	<p>Your name is <span id="firstname"></span> <span id="lastname"></span></p>
 
	<p><button onClick="window.opener.close();">close the parent card</button></p>
 
	<p><button onClick="window.close();">close current card</button></p>
</body>
</html>

Run the make script and you should be able to try out these tricks to the newCard API.

Example app & source can be downloaded here.

Jul 12

The release of PhoneGap-webOS 1.0.0rc1 adds built-in support for touch events. The touch events use the thumbs.js library which has been rolled into PhoneGap-webOS.

To use the touch events in PhoneGap-webOS add the following lines of code to your HTML file.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
<html>
    <head>
        <script type="text/javascript" src="phonegap.js"></script>
    </head>
    <body>
 
        <button id="btnTouchStart">Touch Start</button>
 
        <script>                         
             document.addEventListener('deviceready', function () {
                  // PhoneGap is ready, do all your stuf here
             }, false);
 
            document.querySelector('#btnTouchStart').addEventListener('touchstart', onTouchEvent, false);
 
            function onTouchEvent(event) {
	         navigator.notification.alert(event.type);
            }
        </script> 
 
    </body>
</html>

This will create a button and attach an event listener for a ‘touchstart’ event being triggered from the button. The onTouchEvent method will simple display a notification with the event type being handled.

PhoneGap webOS touchstart event example

Full source code with examples of all touch & mouse events can be found here.