skia2/site/user/quick/android.md

Android

Prerequisites

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

The following libraries/utilities are required in addition to those needed for a standard skia checkout:

• Apache Ant
• The Android SDK: http://developer.android.com/sdk/

$ sudo apt-get install ant git

Check out the source code

Follow the instructions here for downloading the Skia source. Modify .gclient to add the following line to the bottom, and then run gclient sync again:

target_os = ["android"]

Inside your Skia checkout, platform_tools/android contains the Android setup scripts, Android specific dependencies, and the Android Sample App.

Setup the Android SDK

To finish setting up the Android SDK you need to download use the SDK to download the appropriate API level. To do this simply go to the directory where you installed the SDK and run the following commands

# You may want to add this export to your shell's .bash_profile or .profile
export ANDROID_SDK_ROOT=/path/to/android/sdk

$ ANDROID_SDK_ROOT/tools/android update sdk --no-ui --filter android-19

From here you will need to type 'y' to approve the license agreement and that is all. You will then have downloaded the SDK for API level 19 (Android 4.4 KitKat) which will be used to build the Skia SampleApp. You can download as many other Android add-ons or APIs as you want, but you only are required to have this one in order to complete the Skia build process.

Setup Environment for Android

The Android build needs to set up some specific variables needed by both GYP and Make. We make this setup easy for developers by encapsulating all the details into a custom script that acts as a replacement for make.

Custom Android Build Script

The android_ninja script is a wrapper for the ninja command (provided by depot_tools) and is specifically designed to work with the Skia's build system. 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 ninja (see descriptions of some of the other flags here).

export ANDROID_SDK_ROOT=/path/to/android/sdk
export PATH=$PATH:/path/to/depot_tools

cd skia
./platform_tools/android/bin/android_ninja -d nexus_10 # or nexus_7, galaxy_nexus, etc...

The -d option enables the build system to target the build to a specific architecture such as MIPS (generic), x86 (generic) and ARM (generic and device specific flavors for Nexus devices). This in turn allows Skia to take advantage of specific device optimizations (e.g. NEON instructions).

Generate build file from GYP

We use the open-source gyp tool to generate build files from our multiplatform "gyp" files. While most other platforms enable you to regenerate these files using ./gyp_skia it is recommend that you do NOT do this for Android. Instead you can rely on it being run automatically by android_ninja.

Faster rebuilds

You can use ccache to improve the speed of rebuilding:

You may want to add this export to your shell's .bash_profile or .profile

export ANDROID_MAKE_CCACHE=[ccache]

Build and run executables on the device

The build system packages the Skia executables as shared libraries. As such, in order to run any executable on the device you must install the library and a launcher executable on your device. To assist in this process there is a script called android_run_skia that is located in the platform_tools/android/bin directory.

Run correctness tests

First build the app and then run it on an attached device:

./platform_tools/android/bin/android_ninja [-d device_id] dm

# uploads dm binary and resources and runs dm on the attached device
./platform_tools/android/bin/android_run_skia dm --resourcePath /data/local/tmp/skia/resources/

Run performance tests

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

BUILDTYPE=Release ./platform_tools/android/bin/android_ninja [-d device_id] nanobench

# uploads and runs the nanobench binary on the attached device
./platform_tools/android/bin/android_run_skia --release nanobench

If you pass nanobench SKP files, it will benchmark them too.

./platform_tools/android/bin/[linux/mac]/adb push ../skp <dst> # <dst> is dir on device

Finally to run the executable there are two approaches. The simplest of the two run the app on the device like you would do for gm or tests, however this approach will also produce the noisiest results.

# <input> is file/dir on device
./platform_tools/android/bin/android_run_skia --release nanobench --skps <input>

Build and run SampleApp

The SampleApp on Android provides a simple UI for viewing sample slides and gm images.

BUILDTYPE=Debug ./platform_tools/android/bin/android_ninja -d $TARGET_DEVICE

Then, install the app onto the device:

./platform_tools/android/bin/android_install_app

Finally to run the application you must navigate to the Skia Samples application using the application launcher on your device.

Build tools

The Android platform does not support skdiff at this time.

Clean up all generated files

make clean

Debugging on Android

We support debugging on using a GDB wrapper script. The script loads the app onto the device, starts a gdbserver instance with that app, and then enters a GDB client shell on the host. Necessary symbol files are pulled from the device and placed into a temporary folder. The script does not build the app - you'll have to do that first.

# you can include additional arguments in quotes (e.g. "dm --nopdf")
./platform_tools/android/bin/android_gdb_native dm

When the gdb client is ready, insert a breakpoint, and continue to let the program resume execution.