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: 300507
  • Created:
  • Creator: Sheppy
  • Is current revision? No
  • Comment added info about --screen

Revision Content

The Boot to Gecko desktop client, b2g, 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 can be useful during the development of your application, or while working on the Gaia user interface itself.

This article covers building the B2G desktop client, as well as how to use it.

Preparing to build

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

Pulling the code for the first time

There are two sets of code you need: mozilla-central (to get Gecko and the XUL and b2g software frontend code) and Gaia.

Create a directory somewhere into which you want to put it all, then do:

 hg clone http://hg.mozilla.org/mozilla-central src
 git clone https://github.com/mozilla-b2g/gaia gaia

Updating the code for future builds

When you do additional builds later, you'll want to make sure you have the latest code. Here's how to refresh both mozilla-central and Gaia:

cd src
hg pull && hg update
cd ../gaia
git fetch
git merge origin/master

Create a mozconfig

Next, you need to create a .mozconfig file to configure the build system to build the Boot to Gecko client instead of FIrefox. Create the file and put something like this in it:

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

Build

Now you're ready to build. First, you need to build the Boot to Gecko app itself. Just do this from within the mozilla-central (src) directory:

make -f client.mk build

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

Next, you need to generate the required profile directory and do some other preparation of Gaia. The new profile contains a customized extension and other configuration needed to make B2G run properly. So do this in the gaia directory:

cd ${GAIA}
make

Run

Now you're ready to run the B2G client.

Linux

../build/dist/bin/b2g -profile 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);

Mac

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

Make it easier

You can make runing B2G a little easier by setting the values of the shell environment variable B2G_HOMESCREEN to "http://system.gaiamobile.org:8080", and by adding the $MOZ_OBJDIR/dist/bin/ (on Linux) or $MOZ_OBJDIR/dist/B2G.app/Contents/MacOS/ directory to your $PATH.

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

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 whose keyboard doesn't have one, Fn+← should do it (Left Arrow, not Backspace).
  • There is not, currently, a key that simulates the "menu" button on devices that have them.

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 Boot to Gecko desktop client, b2g, 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 can be useful during the development of your application, or while working on the Gaia user interface itself.</p>
<p>This article covers building the B2G desktop client, as well as how to use it.</p>
<h2 id="Preparing_to_build">Preparing to build</h2>
<p>The first thing you 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 you have that, you can pull down the code you'll need and configure to build the B2G desktop client.</p>
<h3 id="Pulling_the_code_for_the_first_time">Pulling the code for the first time</h3>
<p>There are two sets of code you need: mozilla-central (to get <a href="/en-US/docs/Gecko" title="/en-US/docs/Accessibility/AT-APIs/Gecko">Gecko</a> and the <a href="/en-US/docs/XUL" title="/en-US/docs/XUL">XUL</a> and b2g software frontend code) and Gaia.</p>
<p>Create a directory somewhere into which you want to put it all, then do:</p>
<pre>
 hg clone http://hg.mozilla.org/mozilla-central src
 git clone https://github.com/mozilla-b2g/gaia gaia</pre>
<h3 id="Updating_the_code_for_future_builds">Updating the code for future builds</h3>
<p>When you do additional builds later, you'll want to make sure you have the latest code. Here's how to refresh both <a href="/en-US/docs/mozilla-central" title="/en-US/docs/mozilla-central">mozilla-central</a> and Gaia:</p>
<pre>
cd src
hg pull &amp;&amp; hg update
cd ../gaia
git fetch
git merge origin/master
</pre>
<h2 id="Create_a_mozconfig">Create a mozconfig</h2>
<p>Next, you need to create a <code>.mozconfig</code> file to configure the build system to build the Boot to Gecko client instead of FIrefox. Create the file and put something like this in it:</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>
<h2 id="Build">Build</h2>
<p>Now you're ready to build. First, you need to build the Boot to Gecko app itself. Just do this from within the mozilla-central (<code>src</code>) directory:</p>
<pre>
make -f client.mk build
</pre>
<p>The built client will be placed in the <code>../build</code> directory (based on the value you specify for <code>MOZ_OBJDIR</code> in the <code>.mozconfig</code> file).</p>
<p>Next, you need to generate the required profile directory and do some other preparation of Gaia. 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>
cd ${GAIA}
make
</pre>
<h2 id="Run">Run</h2>
<p>Now you're ready to run the B2G client.</p>
<h3 id="Linux">Linux</h3>
<pre>
../build/dist/bin/b2g -profile 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="Mac">Mac</h3>
<pre>
../build/dist/B2G.app/Contents/MacOS/b2g -profile /full/path/to/gaia/profile
</pre>
<h3 id="Make_it_easier">Make it easier</h3>
<p>You can make runing B2G a little easier by setting the values of the shell environment variable <code>B2G_HOMESCREEN</code> to "<span class="nowiki">http://system.gaiamobile.org:8080</span>", and by adding the <code>$MOZ_OBJDIR/dist/bin/</code> (on Linux) or <code>$MOZ_OBJDIR/dist/B2G.app/Contents/MacOS/</code> directory to your <code>$PATH</code>.</p>
<h2>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>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>
<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 whose keyboard doesn't have one, Fn+← should do it (Left Arrow, not Backspace).</li>
  <li>There is not, currently, a key that simulates the "menu" button on devices that have them.</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>
</ul>
Revert to this revision