1Android 2======= 3 4Prerequisites 5------------- 6 7_Currently we only support building Skia for Android on a Linux or Mac host! In addition, 8 we only use the Mac build for local development. All shipping variants are compiled on 9 Linux for performance reasons._ 10 11The following libraries/utilities are required in addition to those needed for a standard skia checkout: 12 13 * The Android SDK: http://developer.android.com/sdk/ 14 15Check out the source code 16------------------------- 17 18Follow the instructions [here](../download) for downloading the Skia source. 19 20Inside your Skia checkout, `platform_tools/android` contains the Android setup 21scripts, Android specific dependencies, and the Android Sample App. 22 23You may need to [install other dependencies](./linux#prerequisites): 24 25 tools/install_dependencies.sh 26 27Setup the Android SDK 28--------------------- 29 30To finish setting up the Android SDK you need to download use the SDK to 31download the appropriate API level. To do this simply go to the directory 32where you installed the SDK and run the following commands 33 34 # You may want to add this export to your shell's .bash_profile or .profile 35 export ANDROID_SDK_ROOT=/path/to/android/sdk 36 37 $ ANDROID_SDK_ROOT/tools/android update sdk --no-ui --filter android-19 38 39From here you will need to type 'y' to approve the license agreement and that 40is all. You will then have downloaded the SDK for API level 19 (Android 4.4 41KitKat) which will be used to build the Skia SampleApp. You can download as 42many other Android add-ons or APIs as you want, but you only are required to 43have this one in order to complete the Skia build process. 44 45Setup Environment for Android 46----------------------------- 47 48The Android build needs to set up some specific variables needed by both GYP 49and Make. We make this setup easy for developers by encapsulating all the 50details into a custom script that acts as a replacement for make. 51 52Custom Android Build Script 53--------------------------- 54 55The android_ninja script is a wrapper for the ninja command (provided by 56depot_tools) and is specifically designed to work with the Skia's build 57system. To use the script you need to call it from Skia's trunk directory with 58the -d option plus any of the options or arguments you would normally pass to 59ninja (see descriptions of some of the other flags here). 60 61 export ANDROID_SDK_ROOT=/path/to/android/sdk 62 export ANDROID_HOME=/path/to/android/sdk 63 export PATH=$PATH:/path/to/depot_tools 64 65 cd skia 66 ./platform_tools/android/bin/android_ninja -d nexus_10 # or nexus_7, galaxy_nexus, etc... 67 68The -d option enables the build system to target the build to a specific 69architecture such as MIPS (generic), x86 (generic) and ARM (generic and device 70specific flavors for Nexus devices). This in turn allows Skia to take 71advantage of specific device optimizations (e.g. NEON instructions). 72 73Generate build file from GYP 74---------------------------- 75 76We use the open-source gyp tool to generate build files from our 77multi-platform "gyp" files. While most other platforms enable you to 78regenerate these files using `./gyp_skia` or `bin/sync-and-gyp` it is 79recommended that you do NOT do this for Android. Instead you can rely 80on it being run automatically by android_ninja. 81 82Faster rebuilds 83--------------- 84 85You can use ccache to improve the speed of rebuilding: 86 87 # You may want to add this export to your shell's .bash_profile or .profile 88 export ANDROID_MAKE_CCACHE=[ccache] 89 90Build and run executables on the device 91--------------------------------------- 92 93The build system packages the Skia executables as shared libraries. As such, 94in order to run any executable on the device you must install the library and 95a launcher executable on your device. To assist in this process there is a 96script called `android_run_skia` that is located in the 97`platform_tools/android/bin` directory. 98 99Run correctness tests 100--------------------- 101 102First build the app and then run it on an attached device: 103 104 ./platform_tools/android/bin/android_ninja [-d device_id] dm 105 106 # uploads dm binary and resources and runs dm on the attached device 107 ./platform_tools/android/bin/android_run_skia dm --resourcePath /data/local/tmp/skia/resources/ 108 109Run performance tests 110--------------------- 111 112Since nanobench tests performance, it usually makes more sense to run it in 113Release mode. 114 115 BUILDTYPE=Release ./platform_tools/android/bin/android_ninja [-d device_id] nanobench 116 117 # uploads and runs the nanobench binary on the attached device 118 ./platform_tools/android/bin/android_run_skia --release nanobench 119 120If you pass nanobench SKP files, it will benchmark them too. 121 122 ./platform_tools/android/bin/[linux/mac]/adb push ../skp <dst> # <dst> is dir on device 123 124Finally to run the executable there are two approaches. The simplest of the 125two run the app on the device like you would do for gm or tests, however this 126approach will also produce the noisiest results. 127 128 # <input> is file/dir on device 129 ./platform_tools/android/bin/android_run_skia --release nanobench --skps <input> 130 131Build and run SampleApp 132----------------------- 133 134The SampleApp on Android provides a simple UI for viewing sample slides and gm images. 135 136 BUILDTYPE=Debug ./platform_tools/android/bin/android_ninja -d $TARGET_DEVICE SampleApp_APK 137 138Then, install the app onto the device: 139 140 ./platform_tools/android/bin/android_install_app 141 142Finally to run the application you can either navigate to the Skia Samples 143application using the application launcher on your device or from the command 144line. The command line option allows you to pass additional details to the 145application (similar to other operating system) that specify where to find 146skp files and other resources. 147 148 ./platform_tools/android/bin/android_launch_app --resourcePath /data/local/tmp/resources 149 150By default if no additional parameters are specified the app will use the default 151parameters... 152 153 --resourcePath /data/local/tmp/skia_resoures 154 --pictureDir /data/local/tmp/skia_skp 155 156 157Android Studio Support 158----------------------- 159 160You can also build and run SampleApp (and some other experimental apps) using Android 161Studio. To create the project either select "import project" from the quickstart 162screen or use File -> Open. In both cases you'll need to select ./platform_tools/android/apps 163as the root directory of your project. 164 165Finally to be able to build within Android studio it needs to know the path to 166ninja so you will need to add a properties file and populate it with the path 167to depot_tools. The syntax and location of that file is... 168 169 # 170 # file location: ./platform_tools/android/apps/gradle.properties 171 # 172 depot_tools.dir=<path_to_depot_tools> 173 174That should be all the setup you need. You should now be able to build and deploy 175SampleApp on ARM, Intel, and MIPS devices. 176 177 178Build tools 179----------- 180 181The Android platform does not support skdiff at this time. 182 183Clean up all generated files 184---------------------------- 185 186 make clean 187 188Debugging on Android 189-------------------- 190 191We support 2 modes of debugging on Android using GDB wrapper scripts. These 192scripts start a gdbserver instance on the device and then enter an interactive 193GDB client shell on your host. All necessary symbol files should 194be pulled from the device and placed into a temporary folder (android_gdb_tmp). 195 196Note: The debugging scripts do not build the app - you'll have to do that first. 197 198 # COMMAND LINE APPS 199 # include additional arguments in quotes (e.g. "dm --nopdf") 200 ./platform_tools/android/bin/android_gdb_native dm 201 202 # SAMPLE APP 203 # make sure you've installed the app on the device first 204 ./platform_tools/android/bin/android_gdb_app [-d device_id] 205 206When the gdb client is ready, insert a breakpoint, and continue to let the 207program resume execution. 208