1 Android 2 ======= 3 4 Prerequisites 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 11 The 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 15 Check out the source code 16 ------------------------- 17 18 Follow the instructions [here](../download) for downloading the Skia source. 19 20 Inside your Skia checkout, `platform_tools/android` contains the Android setup 21 scripts, Android specific dependencies, and the Android Sample App. 22 23 You may need to [install other dependencies](./linux#prerequisites): 24 25 tools/install_dependencies.sh 26 27 Setup the Android SDK 28 --------------------- 29 30 To finish setting up the Android SDK you need to download use the SDK to 31 download the appropriate API level. To do this simply go to the directory 32 where 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 39 From here you will need to type 'y' to approve the license agreement and that 40 is all. You will then have downloaded the SDK for API level 19 (Android 4.4 41 KitKat) which will be used to build the Skia SampleApp. You can download as 42 many other Android add-ons or APIs as you want, but you only are required to 43 have this one in order to complete the Skia build process. 44 45 Setup Environment for Android 46 ----------------------------- 47 48 The Android build needs to set up some specific variables needed by both GYP 49 and Make. We make this setup easy for developers by encapsulating all the 50 details into a custom script that acts as a replacement for make. 51 52 Custom Android Build Script 53 --------------------------- 54 55 The android_ninja script is a wrapper for the ninja command (provided by 56 depot_tools) and is specifically designed to work with the Skia's build 57 system. To use the script you need to call it from Skia's trunk directory with 58 the -d option plus any of the options or arguments you would normally pass to 59 ninja (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 68 The -d option enables the build system to target the build to a specific 69 architecture such as MIPS (generic), x86 (generic) and ARM (generic and device 70 specific flavors for Nexus devices). This in turn allows Skia to take 71 advantage of specific device optimizations (e.g. NEON instructions). 72 73 Generate build file from GYP 74 ---------------------------- 75 76 We use the open-source gyp tool to generate build files from our 77 multi-platform "gyp" files. While most other platforms enable you to 78 regenerate these files using `./gyp_skia` or `bin/sync-and-gyp` it is 79 recommended that you do NOT do this for Android. Instead you can rely 80 on it being run automatically by android_ninja. 81 82 Faster rebuilds 83 --------------- 84 85 You 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 90 Build and run executables on the device 91 --------------------------------------- 92 93 The build system packages the Skia executables as shared libraries. As such, 94 in order to run any executable on the device you must install the library and 95 a launcher executable on your device. To assist in this process there is a 96 script called `android_run_skia` that is located in the 97 `platform_tools/android/bin` directory. 98 99 Run correctness tests 100 --------------------- 101 102 First 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 109 Run performance tests 110 --------------------- 111 112 Since nanobench tests performance, it usually makes more sense to run it in 113 Release 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 120 If 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 124 Finally to run the executable there are two approaches. The simplest of the 125 two run the app on the device like you would do for gm or tests, however this 126 approach 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 131 Build and run SampleApp 132 ----------------------- 133 134 The 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 138 Then, install the app onto the device: 139 140 ./platform_tools/android/bin/android_install_app 141 142 Finally to run the application you can either navigate to the Skia Samples 143 application using the application launcher on your device or from the command 144 line. The command line option allows you to pass additional details to the 145 application (similar to other operating system) that specify where to find 146 skp files and other resources. 147 148 ./platform_tools/android/bin/android_launch_app --resourcePath /data/local/tmp/resources 149 150 By default if no additional parameters are specified the app will use the default 151 parameters... 152 153 --resourcePath /data/local/tmp/skia_resoures 154 --pictureDir /data/local/tmp/skia_skp 155 156 157 Android Studio Support 158 ----------------------- 159 160 You can also build and run SampleApp (and some other experimental apps) using Android 161 Studio. To create the project either select "import project" from the quickstart 162 screen or use File -> Open. In both cases you'll need to select ./platform_tools/android/apps 163 as the root directory of your project. 164 165 Finally to be able to build within Android studio it needs to know the path to 166 ninja so you will need to add a properties file and populate it with the path 167 to 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 174 That should be all the setup you need. You should now be able to build and deploy 175 SampleApp on ARM, Intel, and MIPS devices. 176 177 178 Build tools 179 ----------- 180 181 The Android platform does not support skdiff at this time. 182 183 Clean up all generated files 184 ---------------------------- 185 186 make clean 187 188 Debugging on Android 189 -------------------- 190 191 We support 2 modes of debugging on Android using GDB wrapper scripts. These 192 scripts start a gdbserver instance on the device and then enter an interactive 193 GDB client shell on your host. All necessary symbol files should 194 be pulled from the device and placed into a temporary folder (android_gdb_tmp). 195 196 Note: 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 206 When the gdb client is ready, insert a breakpoint, and continue to let the 207 program resume execution. 208
