How to check out and build Skia on Android

originally written on 17 November 2011

Prerequisites

Currently we only support building Skia for Android on a Linux host!

Required:

• python
• suggested Ubuntu packages: python2.6, python2.6-dev
• Subversion (svn) client
• suggested Ubuntu package: subversion
• Chromium depot_tools: http://www.chromium.org/developers/how-tos/depottools

Optional:

• The Android SDK: http://developer.android.com/sdk/
• This is not needed to build the simplest applications (test, gm, bench).

Check out the source code

We use the "gclient" script (part of the depot_tools toolkit) to manage the Skia-Android source code. Follow the instructions at http://www.chromium.org/developers/how-tos/depottools to get the gclient script from depot_tools.

Instead of checking out trunk directly you will use gclient to checkout the android directory, which will automatically pull the trunk directory for you. Execute the following commands in whatever directory you want to be the root for your Skia on Android development:

curl http://skia.googlecode.com/svn/android/gclient.config -o .gclient
gclient sync

After executing this command you should see two new directories containing the following contents...

• trunk -- contains all the skia sources
• android -- contains the ARM toolchain, Android dependencies, Android Sample App, and setup scripts

Setup Environment for Android

The Android build needs to set up some specific variables needed by both GYP and Make. This can be achieved in one of two ways:

1. You can use our custom script as a replacement for make, or
2. You can modify your shell environment to include those variables.

Custom Make Script (Recommended)

The android_make script is a wrapper for the system's make command and is specifically designed to work with the Makefile in Skia's trunk directory. To use the script you need to call it from Skia's trunk directory with the -d option plus any of the options or arguments you would normally pass to make (see descriptions of some of the other flags here.)

TARGET_DEVICE=xoom     # or nexus_s
cd trunk
../android/bin/android_make -d $TARGET_DEVICE -j

The -d option enables the build system to target the build to a specific device, such as the Nexus S or Xoom. This in turn allows Skia to take advantage of specific device optimizations (e.g. NEON instructions).

Modified Shell Environment (Advanced Only)

It is recommended that after completing these steps in your terminal that you only use this terminal for building Skia on Android since you will get unexpected results if you attempt to build for another target platform (e.g. linux).

source android/bin/android_setup.sh

If the command completed successfully you should see something similar to this as output.

The build is targeting NDK v14 for use on Android 4.0 and above

As you can see from the output above when you build the skia sources you will be building with the Android NDK. Additionally, we need to target the build to a specific device, such as the Nexus S or Xoom. This device target allows Skia to take advantage of specific device optimizations (e.g. NEON instructions). To set this up or change the target device type for subsequent builds simply run the following command with one of the supported options.

setup_device [nexus_s or xoom]

Now your set. You can dive into the Skia sources and compile and run them using the steps documented below.

Generate makefiles

We use the open-source gyp tool to generate Unix makefiles (and analogous build scripts on other platforms) from our multiplatform "gyp" files.

You can generate the Unix makefiles by running ./gyp_skia (or ./gyp_skia -Dskia_scalar-fixed) within the trunk/ directory. Or, you can just rely on it being run automatically by the makefile examples shown below.

Build and run executables on the device

Standalone executables like bench, gm, and tests can only be run on an Android device with root access as the binary must be placed within the system partition to run.

In order to run any executable on an actual device you must complete the following steps first. Start by ensuring that you have a development device attached to your machine. Next, run these commands to make sure that the adb server is running as root, and that the device is properly attached:

sudo ../android/bin/linux/adb kill-server
sudo ../android/bin/linux/adb start-server
../android/bin/linux/adb devices

If you see your device listed then you can proceed to remount the device's system partition in read/write mode. To remount the device run the following commands:

../android/bin/linux/adb root
../android/bin/linux/adb remount

That is the end of the setup of your device and adb. You are now able to build and run any of the following executables on your device.

Build and run tests

cd ../trunk

../android/bin/android_make -d $TARGET_DEVICE -j5 tests BUILDTYPE=Debug
# or, if you are using the Modified Shell Environment...
make -j5 tests BUILDTYPE=Debug

Then, push the executable onto the device and run it.

../android/bin/linux/adb push out/Debug/tests /system/bin/skia_tests
../android/bin/linux/adb logcat -c        # clears out the Android system log
../android/bin/linux/adb shell skia_tests # blocks until the executable finishes running
../android/bin/linux/adb logcat -d        # dumps all log entries since "logcat -c"

Build and run gm ("golden master") tests

The android port does not currently have any gm reference images, but the gm program will still test serialization if run with the --serialize option.

cd ../trunk

../android/bin/android_make -d $TARGET_DEVICE -j5 gm BUILDTYPE=Debug
# or, if you are using the Modified Shell Environment...
make -j5 gm BUILDTYPE=Debug

Then, push the executable onto the device and run it.

../android/bin/linux/adb push out/Debug/gm /system/bin/skia_gm
../android/bin/linux/adb logcat -c  # clears out the Android system log
../android/bin/linux/adb shell skia_gm --serialize # blocks until the executable finishes running
../android/bin/linux/adb logcat -d  # dumps all log entries since "logcat -c"

Build and run bench (performance testbench)

Since bench tests performance, it usually makes more sense to run it in Release mode...

cd ../trunk

../android/bin/android_make -d $TARGET_DEVICE -j5 bench BUILDTYPE=Release
# or, if you are using the Modified Shell Environment...
make -j5 bench BUILDTYPE=Release

Then, push the executable onto the device and run it.

../android/bin/linux/adb push out/Release/bench /system/bin/skia_bench
../android/bin/linux/adb logcat -c        # clears out the Android system log
../android/bin/linux/adb shell skia_bench # blocks until the executable finishes running
../android/bin/linux/adb logcat -d        # dumps all log entries since "logcat -c"

Build and run SampleApp

The Android platform's sample app is not supported at this time.

Build tools

The Android platform does not support skdiff at this time.

Clean up all generated files

make clean