B2G Quickstart for Payments and Identity

This sets you up to make two separate targets:

One for a desktop [simulator] 1
One for the ZTE [device] 2

These are the moving parts:

[mozilla-inbound repo] 3 clone (hg)
[gaia repo] 4 fork (git)
[B2G project clone] 5 (git)

Basic organization

I've structured my directories like so:

b2g-src/
  gaia/       # git clone of my gaia fork
  mi/         # hg clone of my mozilla-inbound user repo
  build/      # build dir that mi will create

b2g/          # git clone of mozilla-b2g/B2G

Prep steps: Setting up Mercurial Queues

You'll need to create an ~/.hgrc file if you don't already have one. These are my settings:

(Note - don't just paste this! Two lines to edit!)

[ui]
merge = kdiff3
username = Your Name <[email protected]>

[diff]
# git diff is required so binary files don't break
git = 1
showfunc = True
unified = 8

[defaults]
diff=-p -U 8
commit= -v

[paths]
# makes it easier to push to try
try = ssh://hg.mozilla.org/try

[extensions]
# I don't even remember what these are all for
graphlog =
hgext.mq =
fetch =
purge =
hgext.rebase =
hgext.extdiff =
hgext.transplant =
rdiff=/home/jed/lib/python/rdiff.py
# this lets you import patches straight from bugzilla
# source: https://hg.mozilla.org/users/robarnold_cmu.edu/qimportbz
# about:    http://robarnold.org/2009/06/02/hg-qimport-my-bugzilla-patch-redux.html
qimportbz=/path/to/your/qimportbz/

[extdiff]
# Creates the command 'hg cdiff' for colorized diff output
cmd.cdiff = colordiff
opts.cdiff = -wuprN

[merge-tools]
# Specify command line
kdiff3.args = $base $local $other -o $output
# Give higher priority
kdiff3.priority = 1

[bookmarks]
track.current = True

Follow the steps in the [introduction to Mercurial queues] 6.

Read the [Mercurial queue workflow] 7 documentation.

Setting up `gaia`

cd b2g-src

git clone (or maybe fork first) https://github.com/mozilla-b2g/gaia

Update with a git pull.

We need to create a default profile that will toggle the native identity features on.

Create the file custom-prefs.js in the root of the gaia directory. Put these lines in it:

pref("dom.identity.enabled", true);
pref("toolkit.identity.debug", true);

Build with:

DEBUG=1 make

You need network to build, since packages will be downloaded from nightly.

If you want to update the custom prefs at any time, you will need to re-build the profile (but not the whole project) with make profile.

Setting up the `mozilla-inbound` repo

This is where we will be working on navigator.id and friends.

First, cd b2g-src; mkdir mi; cd mi

In the mi directory:

hg init .
hg qinit -c    # initializes mercurial queues

Create and edit .hg/hgrc, filling in your LDAP username correctly:

[paths]
default = ssh://<LDAP_username>@[email protected]/users/jparsons_mozilla.com/b2g-payments-identity/
mozilla-inbound = https://hg.mozilla.org/integration/mozilla-inbound/

Create and edit .hg/patches/.hg/hgrc

[paths]
default = http://hg.mozilla.org/users/jparsons_mozilla.com/b2g-payments-identity
default-push = ssh://hg.mozilla.org/users/jparsons_mozilla.com/b2g-payments-identity

You can regularly pull and update:

hg pull
hg update

Whoever is managing the shared user repo (me, in this case), would regularly do:

hg pull mozilla-inbound
hg update
hg push

Don't run make yet!

Follow the steps below to build for desktop, and optionally for the device.

Building for desktop or the device

Desktop builds

Create a .mozconfig file containing:

mk_add_options MOZ_OBJDIR=../build
mk_add_options MOZ_MAKE_FLAGS="-j8 -s"
mk_add_options ENABLE_MARIONETTE=1

ac_add_options --enable-application=b2g

ac_add_options --enable-debug
ac_add_options --enable-debug-symbols
ac_add_options --disable-optimize
ac_add_options --disable-install-strip

ac_add_options --with-ccache
ac_add_options --disable-crashreporter
ac_add_options --enable-gstreamer

# 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

# enable dump() from js
export CXXFLAGS="-DMOZ_ENABLE_JS_DUMP $EXTRA_INCLUDE"

To configure (or reconfigure), say:

make -f client.mk configure

Now with your .mozconfig in place, you can build:

make -f client.mk

You have to regularly blow away the ../build directory. Try that first if make crashes.

If it crashes, try blowing away the build dir and makeing again.

Great! You've already built Gaia, so you can just run b2g like so:

build/dist/bin/b2g -profile gaia/profile --no-remote

You should see the emulator appear in all its glory.

Hotkeys:

ESC for "back" button
Home for to go to home screen. On the Mac, use Fn + left-arrow

MDN has more about [using the B2G desktop client] 8.

Building for the device

Build for the desktop as described in the preceding section.

We clone the b2g project, but we will not use the repo sync script in it. Instead, we will make it use our own mozilla-inbound and gaia code.

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

Create .userconfig and add these lines (adjusting paths accordingly):

# Configuration for custom device builds;  Desktop builds ignore this.

GAIA_PATH=/path/to/b2g-src/gaia
GECKO_PATH=/path/to/b2g-src/mi

VARIANT=user  # 'user' strangely means 'production'
              # this option omits the test apps from the phone

Follow the [B2G Otoro setup instructions] 2. I can't summarize those steps here, because there are downloads and passwords involved. It's a short document that will take you through:

setting up udev (on Linux)
downloading the Adreno driver
installing busybox on the phone

I honestly can't recall which of those steps I had to follow and which were already simplified somehow. But it was pretty straightforward.

Now configure, build, and flash:

./config.sh otoro   # assuming otoro is the correct target
./build.sh
./flash.sh

Running config.sh will download a ton of stuff the first time.

If it crashes (which it will) with a complaint that you don't have libOmxVidEnc.so or some such on your device or in your backup folder, you should [download the official otoro backup folder] 11 (123MB!).

That's that. Time to go play with the phone.

REPL

You can has REPL!

Add to your prefs: pref("b2g.remote-js.enabled", true);

Then:

adb forward tcp:9999 tcp:9999
netcat localhost 9999

Rebooting b2g

So you just crashed your phone in the REPL?

adb shell stop b2g
adb shell start b2g

Testing

We have notes about running xpshell tests in our [native identity warroom notes] 10.

Briefly, to run all xpcshell tests:

TEST_PATH=toolkit/identity/test make -C ../build xpcshell-tests

To run a single test:

SOLO_FILE="test_yourfilename.js" make -C ../build/toolkit/identity/tests check-one

Mochitests will not work in the b2g environment. For example:

# This will fail
TEST_PATH=browser/modules/test make -C ../build mochitest-browser-chrome

To test UI components that require mochi tests, either [push to the try server] 9 or apply your patch in your copy of the pine branch and run your tests there.

jedp/gist:3778932