This article provides a brief guide to some key things you should know when using the Boot to Gecko emulators. This doesn't purport to be a complete user manual; instead, it simply tells you a few useful things that you might not learn on your own.
This guide assumes you've already built one of the emulators; if you haven't, rewind to Building and installing Boot to Gecko!
About the B2G emulators
There are two B2G emulators. The first, built by configuring for "emulator-x86" when running config.sh
, is an x86 device emulator. While this is much faster than emulating the ARM processor, it's not as accurate a representation of what an actual device will work like. Configuring for "emulator" when running config.sh
gets you the ARM device emulator.
Once you've selected, configured, and built an emulator, the rest works the same way from a user standpoint, so the rest of this guide is common to both.
Starting the emulator
To start the B2G emulator, type the following command:
./run-emulator.sh
This will handle all the emulator startup tasks for you. Now wait patiently while the emulator starts up and Boot to Gecko boots up on it. It can take a couple of minutes, so be patient.
When the emulator doesn't work
Sometimes the emulator fails to start up. Welcome to the bleeding edge of technology! Here are some tips for resolving problems.
Make sure the adb server is running
This usually happens because the adb server that handles interacting with the emulated device is either not running or has malfunctioned.
Note: If you're using the adb
built by the B2G build system (which you probably are), it's located in the $B2G/out/host/<platform>/bin
directory. On Mac, this is $B2G/out/host/darwin-x86/bin
, for example.
Look to see if adb
is even running by doing:
ps aux | grep adb
If it's there, do this to kill it, because it's probably not working correctly.
adb kill-server
If it's not there, do this:
adb start-server
Then try running the emulator again. If it's still not working, time to drop in on #b2g on irc.mozilla.org for help.
Erase configuration settings
Sometimes, out of date configuration settings on your emulated device can cause it to misbehave. You can delete the IndexedDB database fix this, as follows:
- Make sure adb is running, as described in Make sure the adb server is running.
- Start up the emulator.
- in the terminal on the host computer, go into the root code build directory for your emulator, then type:
out/host/<platform>/bin/adb -e shell
; on Mac, this would beout/host/darwin-x86/bin/adb -e shell
. - Now you're in the adb shell, and can execute shell commands on your emulated device. Let's stop B2G on the device:
stop b2g
. - Delete the IndexedDB database:
rm -rf /data/local/indexedDB
. - Restart B2G on the emulated device:
start b2g
.
Hopefully at this point you will wind up in the Gaia interface and all will be well.
Configuring the emulator
There are several options you can change to adjust the emulator to be more similar to the device you want to emulate. This section provides some basic information on how to do that. You can adjust the emulator's configuration by editing the run-emulator.sh
script (or, ideally, a copy of it). Only a few of the most useful parameters are discussed here; you'll want to look at the qemu site for details on the others.
run-emulator.sh
for each device you want to simulate; this makes it easy to start up with different configurations.Changing skins
By default, the emulator starts up in HVGA mode; that's half-VGA, or 320x480 pixels. This is specified by the -skin
parameter given to the emulator when started up. You can switch to a different display mode by editing the run-emulator.sh
script (or, ideally, a copy of it). The provided skins are:
- HVGA (320x480)
- QVGA (240x320)
- WQVGA (240x400)
- WQVGA432 (240x432)
- WSVGA (1024x600)
- WVGA800 (480x800)
- WVGA854 (480x854)
- WXGA720 (1280x720)
- WXGA800 (1280x800)
The skins are located in the B2G/development/tools/emulator/skins
directory. It's worth noting that the format for skins is quite simple; if you look at them, they're simply folders filled with PNG files for the various user interface objects and a text file called layout
which describes the layout of the interface and screen area. It's fairly simple to create custom skins if needed.
Changing memory size
Another option you may wish or need to configure is the device memory size. The default is 512 MB; however, if the device you're emulating has more or less memory, it is likely important that you adjust this setting to match, to ensure your app will run on the baseline device you want to work on. To do this, change the value of the -memory
parameter to the size you need in megabytes. Other than the 512 MB default, 256 MB and 1024 MB are likely ones you'll want to test with.
To change the amount of emulated storage capacity for the device (that is, the storage space for local data, like the flash storage on a mobile phone or the hard drive on a computer), change the value of the -partition-size
parameter. The default is 512 MB, but you can specify any size in MB you need in order to simulate the kind of device you need to test for.
Network Connectivity
If for some reason you cannot connect your emulator to the internet you can run the following command from your commandline:
adb shell setprop net.dns1 10.0.2.3