Before you begin: You want to do this on a Mac. I have been using Linux for months, and unresolved redraw issues (white screen of death) are killing me. Mac works great. Use OSX.
This sets you up to make two separate targets:
These are the moving parts:
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
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 <you@mozilla.com>
[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.
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.
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>@mozilla.com@hg.mozilla.org/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.
Create a .mozconfig file containing:
mk_add_options MOZ_OBJDIR=../build
mk_add_options MOZ_MAKE_FLAGS="-j8 -s" # set -j to the number of cores you want it to use
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 on Linux like so (obviously substituting your build and gaia dir paths):
$BUILD_DIR/dist/bin/b2g -profile $GAIA_DIR/profile --no-remote
On Mac, you want to run the generated app thingy:
$BUILD_DIR/dist/B2GDebug.app/Contents/MacOS/b2g -profile $GAIA_DIR/profle
(Note: You can actually run it either way on OSX, but if you don't do it the latter way, the finder will think it's a terminal window, and the keyboard input will be routed down to the window you launched b2g from.)
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.
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 phoneFollow the [B2G Unagi 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
- downloading the unagi backup directory
- 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 unagi # assuming unagi 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 probably haven't downloaded [the backup folder] 11.
That's that. Time to go play with the phone.
You can has REPL!
Add to your prefs: pref("b2g.remote-js.enabled", true);
Then:
adb forward tcp:9999 tcp:9999
netcat localhost 9999
So you just crashed your phone in the REPL?
adb shell stop b2g
adb shell start b2g
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.
##Questions to Ask Yourself when Hope Seems Lost
- did you blow away your gaia profile? If not,
rm -rf profile && make - did you
git pull --rebase mozilla masteryour gaia tree? try it! - did you blow away your gecko build dir? May be necessary after inbound merges.
- are there any b2g processes running?
ps -eaf | grep b2gand kill them. - have you tried burning incense, pouring libations, and chanting? You should!