Getting started with the Android Eclipse build backend for Fennec

Prerequisities

You’ll need:

• An appropriate version of Eclipse. I’ve tested both Kepler Service Release 1 (Build id: 20130919-0819) and Luna Release (Build id: 20131219-0014) on Mac OS X.
• To bump Eclipse’s memory limits, as described in this stack overflow answer. If you don’t, you’ll hit GC issues because Android’s dex takes a good deal of memory.
• To install the Eclipse ADT plugin.
• Your mozconfig to include --enable-application=mobile/android.

Quick start

Build and package your tree:

mach build && mach package

Generate the Android Eclipse project files with:

mach build-backend --backend=AndroidEclipse

On success, you should see output containing a line like:

Wrote 5 Android Eclipse projects to /Users/nalexander/Mozilla/gecko/objdir-droid/android_eclipse; 5 created; 0 updated

Open Eclipse. If you haven’t already, you’ll be prompted to enter a workspace location. After you do so, you’ll see something like the following (minus the About dialog):

In a fresh Eclipse workspace, go to File > Import… and select General > Existing Projects into Workspace:

Enter the path printed by mach build-backend --backend=AndroidEclipse. You can safely ignore the BackgroundInstrumentationTests project. Click OK.

You should see a good deal of action in the console, some errors, and lots of repeated build steps. Eventually, this should settle down:

Now you should be able to begin editing the Java source code of Fennec and Robocop. Saving should trigger an incremental build, which will print output to the console (which, unfortunately, gets continually erased and can’t be easily saved) before completing. These incremental builds should be pretty fast; on my system, a trivial change takes about a second to compile.

These compilation steps do not actually build and dex an Android APK. To do so, right click the Fennec project and select Run as… > Android Application. You should see console logs saying that Fennec is being packaged and deployed to the device. Some time later you should have a freshly built Fennec re-started on your device. For me, this takes about 45 seconds — Eclipse is dexing several megs of Java .class files, signing about 20 megs of libraries, and then sending the resulting APK to my device’s storage.

Get out of jail card

It is possible (easy) to confuse Eclipse’s builder. In this case, select all the projects you have open, right click, and select Refresh. Then, go to Project > Clean… and clean all projects. You should see a lot of churn, but eventually you should get a clean build. In rare cases (including changes to moz.build files) the Eclipse project files will be stale and you’ll need to re-run:

mach build-backend --backend=AndroidEclipse

Remember to refresh all projects and clean build after re-running the Android Eclipse backend.

Future

Some things for future work:

• making the Eclipse build integration smoother and more predictable;
• making it easier to use Eclipse and rebuild omni.ja;
• support for building and running tests from Eclipse;
• squashing warnings, so we can see when we add new warnings;
• documentation;
• a getting started/best practices guide for Eclipse;
• a build backend for IntelliJ project files.

Thanks

This work couldn’t have happened without the initial work and testing of bnicholson and the tireless reviews and encouragement of gps.

Feedback

Feedback is always appreciated: discussion is best conducted on the mobile-firefox-dev mailing list and I’m nalexander on IRC. File tickets concerning the build system in Core :: Build Config and CC me.