Building for Android

Josh Matthews edited this page Aug 2, 2018 · 69 revisions

Get Android tools

After cloning the repository and installing dependencies common to all targets, this should obtain the Android-specific tools:

./mach bootstrap-android

Build Servo

After that, in some sub-commands the --android flag is short for --target armv7-linux-androideabi

# Replace "--release" with "--dev" to create an unoptimized debug build.
./mach build --release --android
./mach package --release --android

For running in an emulator however, you’ll likely want to build for Android x86 instead:

./mach build --release --target i686-linux-android
./mach package --release --target i686-linux-android

Set up toolchain manually

If ./mach bootstrap-android does not work or is not appropriate, the Android tools can be installed manually.

First, we need the Android SDK and NDK and associated development tools:

To install the NDK and SDK, refer to the guidelines on the website. When you install the SDK, run the UI tool at tools/android (on Mac, this would be under /Users/<username>/Library/Android/sdk) and update the SDK in order to install a full set of Android libraries. You may use the Android-18 platform. From the commandline, you may also do:

tools/bin/sdkmanager platform-tools "platforms;android-18" "build-tools;23.0.3"

The NDK must be version 12 or 12b. Versions before and after change the layout of the NDK and add or remove files.

Set the following environment variables while building. (You may want to export them from a configuration file like .bashrc (~/.bash_profile for Mac OS X).)

ANDROID_SDK="/path/to/sdk"
ANDROID_NDK="/path/to/ndk"
PATH=$PATH:$ANDROID_SDK/platform-tools

If you're on Debian (not Ubuntu), you may need to install the packages below.

sudo apt-get install curl ia32-libs ant

If you're on Ubuntu, you may need to do:

sudo apt-get install curl libc6:i386 ant lib32z1 openjdk-8-jdk

You might have to install cmake 3.5.2 if you run into Angle compilation errros (see this issue).

If you're on OSX, install these packages:

brew install nspr ant

Installing and running on-device

To install Servo on a hardware device, first set up your device for development.

Run this command to install the Servo package on your device. Replace --release with --dev if you are building in debug mode.

./mach install --release --android

To start Servo, tap the "Servo" icon in your launcher screen, or run this :

./mach run --android https://www.mozilla.org/

Force-stop:

adb shell am force-stop com.mozilla.servo/com.mozilla.servo.MainActivity

If the above doesn't work, try this:

adb shell am force-stop com.mozilla.servo

Uninstall:

adb uninstall com.mozilla.servo

Profiling

We are currently using a Nexus 9 for profiling, because it has an NVidia chipset and supports the NVidia System Profiler. First, install the profiler.

You will then need to root your Nexus 9. There are a variety of options, but I found the CF-Auto-Root version the easiest. Just follow the instructions on that page (download, do the OEM unlock, adb reboot bootloader, fastboot boot image/CF-Auto-Root-flounder-volantis-nexus9.img) and you should end up with a rooted device.

If you want reasonable stack backtraces, you should add the flags -fno-omit-frame-pointer -marm -funwind-tables to the CFLAGS (simplest place to do so is in the mach python scripts that set up the env for Android). Also, remember to build with -r for release!

Installing and running in the emulator

To set up the emulator, use the android tool installed with the SDK. Create a default Nexus7 device with an SDCard of size greater than 100MB. After creating it, open the file ~/.android/avd/nexus7.avd/config.ini and change the hw.dPad and hw.mainKeys configuration files to yes.

Installation:

./mach install --android --release

Running:

./mach run --android https://www.mozilla.org/

Force-stop:

adb shell am force-stop com.mozilla.servo

Uninstall:

adb uninstall com.mozilla.servo

Viewing RUST_LOG output

If you have enabled the RUST_LOG environment variable in main.rs, we will redirect those messages generated by the Rust runtime to the Android logging facilities. To display those items, use:

adb logcat

Getting meaningful symbols out of crash reports

Copy the logcat output that includes the crash information and unresolved symbols to a temporary log file. Run ndk-stack -sym target/armv7-linux-androideabi/debug/apk/obj/local/armeabi-v7a/lib/ -dump log. This should resolve any symbols from libsimpleservo.so that appear in the output. The ndk-stack tool is found in the NDK root directory.

Debugging on-device

First, you will need to enable debugging in the project files by adding android:debuggable="true" to the application tag in servo/support/android/apk/app/src/main/AndroidManifest.xml.

~/android-ndk-r9c/ndk-gdb \
    --adb=/Users/larsberg/android-sdk-macosx/platform-tools/adb \
    --project=servo/support/android/apk/app/src/main/
    --launch=com.mozilla.servo.MainActivity \
    --verbose

To get symbols resolved, you may need to provide additional library paths (at the gdb prompt):
set solib-search-path /Users/larsberg/servo/support/android/apk/obj/local/armeabi/:/Users/larsberg/servo/support/android/apk/libs/armeabi

OR you may need to enter the same path names as above in the support/android/apk/libs/armeabi/gdb.setup file.

If you are not able to get past the "Application Servo (process com.mozilla.servo) is waiting for the debugger to attach." prompt after entering continue at (gdb) prompt, you might have to set Servo as the debug app (Use the "Select debug app" option under "Developer Options" in the Settings app). If this doesn't work, Stack Overflow will help you.

The ndk-gdb debugger may complain about ... function not defined when you try to set breakpoints. Just answer y when it asks you to set breakpoints on future library loads. You will be able to catch your breakpoints during execution.

x86 build

To build a x86 version, follow the above instructions, but replace --android with --target=i686-linux-android. The x86 emulator will need to support GLES v3 (use AVS from Android Studio v3+).

WebVR support

  • Enable WebVR preference: "dom.webvr.enabled": true
  • ./mach build --release --android --features googlevr
  • ./mach package --release --android --flavor googlevr
  • ./mach install --release --android
  • ./mach run --android https://threejs.org/examples/webvr_rollercoaster.html (warning: the first run loads the default url sometimes after a clean APK install)

PandaBoard

If you are using a PandaBoard, Servo is known to run on Android with the instructions above using the following build of Android for PandaBoard: http://releases.linaro.org/12.10/android/leb-panda

Important Notices.

Different from Linux or Mac, on Android, Servo's program entry is in the library, not executable. So we can't execute the program with command line arguments. To approximate command line arguments, we have a hack for program entry on android: You can put command-line arguments, one per line, in the file /sdcard/servo/android_params on your device. You can find a default android_params property under resources in the Servo repo.

Default settings:

default font directory : /system/fonts (in android)
default resource path : /sdcard/servo (in android)
default font configuration : /sdcard/servo/.fcconfig (in android)
default fallback font : Roboto
Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.