Using the B2G desktop client

  • Revision slug: Mozilla/Boot_to_Gecko/Using_the_B2G_desktop_client
  • Revision title: Using the B2G desktop client
  • Revision id: 332113
  • Created:
  • Creator: MarkGiffin
  • Is current revision? No
  • Comment copy edits

Revision Content

The Firefox OS desktop client, also called the B2G desktop client, lets you run Gaia and web apps in a Gecko-based environment somewhat similar to an actual device. It doesn't emulate device hardware, so it's not adequate for testing device APIs, and isn't a replacement for testing on actual hardware. However, it does have a several APIs enabled that aren't available on Firefox such as the Contacts and Settings APIs. It can therefore be useful during the development of your application, or while working on the Gaia user interface itself.

This article covers downloading or building the Firefox OS desktop client, as well as how to use it.

Download a nightly build

Note: v1 is shipping in Aurora. There are also nightly builds based on mozilla-central here:
http://ftp.mozilla.org/pub/mozilla.org/b2g/nightly/latest-mozilla-central/

Just like Firefox Nightlies, the Firefox OS desktop client is built every day from the latest source code. The latest build is available from the Mozilla FTP server. Be sure to pick the latest version and the right archive for your operating system. This lets you bypass having to build it yourself. In addition, you don't have to download Gaia on your own either.

Be sure to install the application in a writeable location; the application needs to be able to update included the Gaia profile.

You can now skip ahead to Running the desktop client.

Building the desktop client

The first thing we need to do is set up a standard Mozilla build environment. Once we have that, we can pull down the code we'll need and configure to build the Firefox OS desktop client.

Downloading the code for the first time

In a directory where we'd like the source code to go, let's clone the mozilla-central repository that contains all of Gecko:

 hg clone http://hg.mozilla.org/mozilla-central

Updating the code

When we do subsequent builds later, we'll want to make sure we have the latest code. Here's how to pull the latest changes:

cd mozilla-central
hg pull -u

Create a mozconfig

Next, we need to create a mozconfig file in the mozilla-central directory to configure the build system to build the Boot to Gecko client instead of Firefox:

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

Building

Now we're ready to build the desktop client with the following command issued from the mozilla-central directory:

make -f client.mk

The built client will be placed in the ../build/dist directory (based on the value you specify for MOZ_OBJDIR in the mozconfig file).

Downloading Gaia

By default the desktop client will show an empty screen because it doesn't know which web app to load initially as the system app. The collection of system apps and default apps that come with Firefox OS is called Gaia.

To download Gaia for the first time, let's clone the source code repository on GitHub:

git clone https://github.com/mozilla-b2g/gaia
cd gaia

To update an already existing clone of Gaia, we can pull in the latest changes from GitHub:

cd gaia
git pull

Generating a profile

Next we need to set up Gaia's apps for the desktop client. This includes packaging the Gaia apps in the same way like they would be installed on the device, as well as setting up the permissions for the privileged system apps. We do this by generating a profile. The following command will take care of that: The new profile contains a customized extension and other configuration needed to make B2G run properly. So do this in the gaia directory:

make

This should create a profile directory below the gaia directory.

Running the desktop client

Once you've built the client and downloaded Gaia (or downloaded and installed the nightly desktop application), you're ready to fire up the Firefox OS desktop client.

Running on Linux

To run the desktop client on Linux using the embedded Gaia profile, just run the b2g executable. If you want to specify a different Gaia profile, you need to bypass the b2g wrapper program and run the b2g-bin binary. The binary is in the archive you downloaded earlier or in the ../build/dist/bin directory if you built the client yourself.

.../b2g-bin -profile gaia/profile

You may experience annoying rendering problems. To avoid them, add the following line to your gaia/profile/prefs.js file:

user_pref("layers.acceleration.disabled", true);

Running on Mac

If you downloaded the nightly build, you can simply launch it from the Finder as usual. Any console output is visible by running the standard Console utility program included with your Mac.

If you want to specify a different Gaia profile, you need to bypass the b2g wrapper program and run the b2g-bin binary. The command line is slightly more complicated due to the location of the b2g-bin binary and the need for absolute paths when specifying the profile directory:

.../B2G.app/Contents/MacOS/b2g-bin -profile /full/path/to/gaia/profile

Running on Windows

Running the nightly build on Windows is as simple as launching b2g.exe. If you want to customize the execution, you can do so by running the b2g-bin.exe executable instead; this bypasses the wrapper program that automatically uses the bundled Gaia.

Note: Due to Bug 795484, the application currently crashes on startup on Windows.

Command line options

There are a number of command line options you can use to adjust the runtime experience while using the desktop client. You can get a list by using the -help option. This section covers some of the particularly interesting ones.

Specifying the screen size

You can specify the screen size of the device you want to simulate using the --screen option:

b2g --screen=<width>x<height>[@<dpi>]

Where <width>, <height>, and <dpi> are fairly self-explanatory parameters: the width and height of the device's screen in pixels and the device resolution in DPI. For example:

b2g --screen=320x480
b2g --screen=320x480@160

Optionally, you can specify certain devices by name to simulate their screen size and resolution:

  • iphone
  • ipad
  • nexus_s
  • galaxy_nexus
  • galaxy_tab
  • wildfire
  • tattoo
  • salsa
  • chacha

Opening the JavaScript console

You can open the JavaScript console when launching the desktop B2G client by launching it from the command line with the -jsconsole flag. After building, just do:

.../b2g -jsconsole -profile /path/to/your/profile

If you've installed the nightly build on a Mac, you can do the following:

/Applications/B2G.app/Contents/MacOS/b2g-bin -jsconsole -profile /path/to/your/profile

Launching a specific application at startup

You can now specify an application to be launched automatically when b2g starts up in the desktop client. This is done as soon as the rest of the system is done loading up. To do this, just use the --runapp option, which takes as a parameter the name of the application to run. For example:

 .../b2g-bin -profile /path/to/your/gaia/profile --runapp email

Before looking for an app to launch, the specified name is normalized by converting it to all lower case and removing all dashes and spaces. This normalized name is then compared to similarly normalized names from the manifests of available apps' manifests.

For example, the name of the email app is currently "E-mail", but --runapp email will work because of this normalization.

If you specify the --runapp option without an argument, or with an empty argument, the b2g client will output to your terminal a list of the known applications as well as a brief usage message.

Note: Using the --runapp option disables the lock screen as a side effect and does not re-enable it. It's assumed that you won't use this command on a profile on which you will be testing the lock screen, or you will turn it back on manually in Settings application. Feel free to contribute a patch to change this behavior if it's a problem.

Usage tips

This section provides a few helpful tips to using the B2G desktop client.

  • The ESC key performs the same function as the "back" button.
  • The Home key performs the same function as the "home" button; if you're on a Mac, the Home key is available as Fn+← (Fn + Left Arrow).

Next steps

Now that you have a desktop build of Boot to Gecko running, you can do testing, development, and other work in it:

Revision Source

<p>The Firefox OS desktop client, also called the <em>B2G desktop client</em>, lets you run Gaia and web apps in a Gecko-based environment somewhat similar to an actual device. It doesn't emulate device hardware, so it's not adequate for testing device APIs, and isn't a replacement for testing on actual hardware. However, it does have a several APIs enabled that aren't available on Firefox such as the Contacts and Settings APIs. It can therefore be useful during the development of your application, or while working on the Gaia user interface itself.</p>
<p>This article covers downloading or building the Firefox OS desktop client, as well as how to use it.</p>
<h2 id="Download_a_nightly_build">Download a nightly build</h2>
<div class="note">
  <p><strong>Note:</strong> v1 is shipping in Aurora. There are also nightly builds based on <code>mozilla-central</code> here:<br />
    <a href="http://ftp.mozilla.org/pub/mozilla.org/b2g/nightly/latest-mozilla-central/" title="http://ftp.mozilla.org/pub/mozilla.org/b2g/nightly/latest-mozilla-central/">http://ftp.mozilla.org/pub/mozilla.org/b2g/nightly/latest-mozilla-central/</a></p>
</div>
<p>Just like <a href="http://nightly.mozilla.org" title="http://nightly.mozilla.org">Firefox Nightlies</a>, the Firefox OS desktop client is built every day from the latest source code. The latest build is <a href="http://ftp.mozilla.org/pub/mozilla.org/b2g/nightly/latest-mozilla-aurora/" title="http://ftp.mozilla.org/pub/mozilla.org/b2g/nightly/latest-mozilla-central/">available from the Mozilla FTP server</a>. Be sure to pick the latest version and the right archive for your operating system. This lets you bypass having to build it yourself. In addition, you don't have to download Gaia on your own either.</p>
<p>Be sure to install the application in a writeable location; the application needs to be able to update included the Gaia profile.</p>
<p>You can now skip ahead to <a href="#Running_the_desktop_client" title="#Running_the_desktop_client">Running the desktop client</a>.</p>
<h2 id="Building_the_desktop_client">Building the desktop client</h2>
<p>The first thing we need to do is set up a <a href="/En/Developer_Guide/Build_Instructions#Build_prerequisites" title="En/Developer_Guide/Build_Instructions#Build_prerequisites">standard Mozilla build environment</a>. Once we have that, we can pull down the code we'll need and configure to build the Firefox OS desktop client.</p>
<h3 id="Downloading_the_code_for_the_first_time">Downloading the code for the first time</h3>
<p>In a directory where we'd like the source code to go, let's clone the <code>mozilla-central</code> repository that contains all of Gecko:</p>
<pre>
 hg clone http://hg.mozilla.org/mozilla-central
</pre>
<h3 id="Updating_the_code">Updating the code</h3>
<p>When we do subsequent builds later, we'll want to make sure we have the latest code. Here's how to pull the latest changes:</p>
<pre>
cd mozilla-central
hg pull -u
</pre>
<h3 id="Create_a_mozconfig">Create a mozconfig</h3>
<p>Next, we need to create a <code>mozconfig</code> file in the <code>mozilla-central</code> directory to configure the build system to build the Boot to Gecko client instead of Firefox:</p>
<pre>
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</pre>
<h3 id="Building">Building</h3>
<p>Now we're ready to build the desktop client with the following command issued from the <code>mozilla-central</code> directory:</p>
<pre>
make -f client.mk
</pre>
<p>The built client will be placed in the <code>../build/dist</code> directory (based on the value you specify for <code>MOZ_OBJDIR</code> in the <code>mozconfig</code> file).</p>
<h2 id="Downloading_Gaia">Downloading Gaia</h2>
<p>By default the desktop client will show an empty screen because it doesn't know which web app to load initially as the system app. The collection of system apps and default apps that come with Firefox OS is called Gaia.</p>
<p>To download Gaia for the first time, let's clone the source code repository on GitHub:</p>
<pre>
git clone https://github.com/mozilla-b2g/gaia
cd gaia</pre>
<p>To update an already existing clone of Gaia, we can pull in the latest changes from GitHub:</p>
<pre>
cd gaia
git pull
</pre>
<h3 id="Generating_a_profile">Generating a profile</h3>
<p>Next we need to set up Gaia's apps for the desktop client. This includes packaging the Gaia apps in the same way like they would be installed on the device, as well as setting up the permissions for the privileged system apps. We do this by generating a profile. The following command will take care of that: The new profile contains a customized extension and other configuration needed to make B2G run properly. So do this in the <code>gaia</code> directory:</p>
<pre>
make
</pre>
<p>This should create a <code>profile</code> directory below the <code>gaia</code> directory.</p>
<h2 id="Running_the_desktop_client">Running the desktop client</h2>
<p>Once you've built the client and downloaded Gaia (or downloaded and installed the nightly desktop application), you're ready to fire up the Firefox OS desktop client.</p>
<h3 id="Running_on_Linux">Running on Linux</h3>
<p>To run the desktop client on Linux using the embedded Gaia profile, just run the <code>b2g</code> executable. If you want to specify a different Gaia profile, you need to bypass the <code>b2g</code> wrapper program and run the <code>b2g-bin</code> binary. The binary is in the archive you downloaded earlier or in the <code>../build/dist/bin</code> directory if you built the client yourself.</p>
<pre>
.../b2g-bin -profile gaia/profile
</pre>
<p>You may experience annoying rendering problems. To avoid them, add the following line to your <code>gaia/profile/prefs.js</code> file:</p>
<pre>
user_pref("layers.acceleration.disabled", true);
</pre>
<h3 id="Running_on_Mac">Running on Mac</h3>
<p>If you downloaded the nightly build, you can simply launch it from the Finder as usual. Any console output is visible by running the standard Console utility program included with your Mac.</p>
<p>If you want to specify a different Gaia profile, you need to bypass the <code>b2g</code> wrapper program and run the <code>b2g-bin</code> binary. The command line is slightly more complicated due to the location of the <code>b2g-bin</code> binary and the need for absolute paths when specifying the profile directory:</p>
<pre>
.../B2G.app/Contents/MacOS/b2g-bin -profile /full/path/to/gaia/profile
</pre>
<h3 id="Running_on_Windows">Running on Windows</h3>
<p>Running the nightly build on Windows is as simple as launching <code>b2g.exe</code>. If you want to customize the execution, you can do so by running the <code>b2g-bin.exe</code> executable instead; this bypasses the wrapper program that automatically uses the bundled Gaia.</p>
<div class="note">
  <p><strong>Note:</strong> Due to <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=795484" title="https://bugzilla.mozilla.org/show_bug.cgi?id=795484">Bug 795484</a>, the application currently crashes on startup on Windows.</p>
</div>
<h2 id="Command_line_options">Command line options</h2>
<p>There are a number of command line options you can use to adjust the runtime experience while using the desktop client. You can get a list by using the <code>-help</code> option. This section covers some of the particularly interesting ones.</p>
<h3 id="option-screen" name="option-screen">Specifying the screen size</h3>
<p>You can specify the screen size of the device you want to simulate using the <code>--screen</code> option:</p>
<pre>
b2g --screen=<em>&lt;width&gt;</em>x<em>&lt;height&gt;</em>[@<em>&lt;dpi&gt;</em>]</pre>
<p>Where <em>&lt;width&gt;</em>, <em>&lt;height&gt;</em>, and <em>&lt;dpi&gt;</em> are fairly self-explanatory parameters: the width and height of the device's screen in pixels and the device resolution in DPI. For example:</p>
<pre>
b2g --screen=320x480
b2g --screen=320x480@160
</pre>
<p>Optionally, you can specify certain devices by name to simulate their screen size and resolution:</p>
<ul>
  <li><code>iphone</code></li>
  <li><code>ipad</code></li>
  <li><code>nexus_s</code></li>
  <li><code>galaxy_nexus</code></li>
  <li><code>galaxy_tab</code></li>
  <li><code>wildfire</code></li>
  <li><code>tattoo</code></li>
  <li><code>salsa</code></li>
  <li><code>chacha</code></li>
</ul>
<h3 id="option-console" name="option-console">Opening the JavaScript console</h3>
<p>You can open the JavaScript console when launching the desktop B2G client by launching it from the command line with the <code>-jsconsole</code> flag. After building, just do:</p>
<pre>
.../b2g -jsconsole -profile <em>/path/to/your/profile</em></pre>
<p>If you've installed the nightly build on a Mac, you can do the following:</p>
<pre>
/Applications/B2G.app/Contents/MacOS/b2g-bin -jsconsole -profile <em>/path/to/your/profile</em></pre>
<h3 id="option-runapp" name="option-runapp">Launching a specific application at startup</h3>
<p>You can now specify an application to be launched automatically when b2g starts up in the desktop client. This is done as soon as the rest of the system is done loading up. To do this, just use the <code>--runapp</code> option, which takes as a parameter the name of the application to run. For example:</p>
<pre>
 .../b2g-bin -profile <em>/path/to/your/gaia/profile</em> --runapp email</pre>
<p>Before looking for an app to launch, the specified name is normalized by converting it to all lower case and removing all dashes and spaces. This normalized name is then compared to similarly normalized names from the manifests of available apps' manifests.</p>
<p>For example, the name of the email app is currently "E-mail", but <code>--runapp email</code> will work because of this normalization.</p>
<p>If you specify the <code>--runapp</code> option without an argument, or with an empty argument, the b2g client will output to your terminal a list of the known applications as well as a brief usage message.</p>
<div class="note">
  <p><strong>Note:</strong> Using the <code>--runapp</code> option disables the lock screen as a side effect and does not re-enable it. It's assumed that you won't use this command on a profile on which you will be testing the lock screen, or you will turn it back on manually in Settings application. Feel free to contribute a patch to change this behavior if it's a problem.</p>
</div>
<h2 id="Usage_tips">Usage tips</h2>
<p>This section provides a few helpful tips to using the B2G desktop client.</p>
<ul>
  <li>The ESC key performs the same function as the "back" button.</li>
  <li>The Home key performs the same function as the "home" button; if you're on a Mac, the Home key is available as Fn+← (Fn + Left Arrow).</li>
</ul>
<h2 id="Next_steps">Next steps</h2>
<p>Now that you have a desktop build of Boot to Gecko running, you can do testing, development, and other work in it:</p>
<ul>
  <li><a href="/en/Mozilla/Boot_to_Gecko/Debugging_on_Boot_to_Gecko" title="en/Mozilla/Boot_to_Gecko/Debugging_on_Boot_to_Gecko">Debugging on Boot to Gecko</a></li>
  <li><a href="/en/Mozilla/Boot_to_Gecko/Testing_Boot_to_Gecko" title="en/Mozilla/Boot_to_Gecko/Testing_Boot_to_Gecko">Testing Boot to Gecko</a></li>
  <li><a href="http://blog.johnford.org/desktop-b2g-include-gaia/" title="http://blog.johnford.org/desktop-b2g-include-gaia/">Desktop B2G builds now include Gaia</a></li>
</ul>
Revert to this revision