1Android
2=======
3
4Prerequisites
5-------------
6
7_Currently we only support building Skia for Android on a Linux or Mac host!_
8
9The following libraries/utilities are required in addition to those needed for a standard skia checkout:
10
11  * Apache Ant
12  * The Android SDK: http://developer.android.com/sdk/
13
14~~~~
15$ sudo apt-get install ant git
16~~~~
17
18Check out the source code
19-------------------------
20
21Follow the instructions [here](../download) for downloading the Skia source. Modify .gclient to add the following line to
22the bottom, and then run gclient sync again:
23
24    target_os = ["android"]
25
26Inside your Skia checkout, `platform_tools/android` contains the Android setup
27scripts, Android specific dependencies, and the Android Sample App.
28
29Setup the Android SDK
30---------------------
31
32To finish setting up the Android SDK you need to download use the SDK to
33download the appropriate API level.  To do this simply go to the directory
34where you installed the SDK and run the following commands
35
36    # You may want to add this export to your shell's .bash_profile or .profile
37    export ANDROID_SDK_ROOT=/path/to/android/sdk
38
39    $ ANDROID_SDK_ROOT/tools/android update sdk --no-ui --filter android-19
40
41From here you will need to type 'y' to approve the license agreement and that
42is all.  You will then have downloaded the SDK for API level 19 (Android 4.4
43KitKat) which will be used to build the Skia SampleApp.  You can download as
44many other Android add-ons or APIs as you want, but you only are required to
45have this one in order to complete the Skia build process.
46
47Setup Environment for Android
48-----------------------------
49
50The Android build needs to set up some specific variables needed by both GYP
51and Make. We make this setup easy for developers by encapsulating all the
52details into a custom script that acts as a replacement for make.
53
54Custom Android Build Script
55---------------------------
56
57The android_ninja script is a wrapper for the ninja command (provided by
58depot_tools) and is specifically designed to work with the Skia's build
59system. To use the script you need to call it from Skia's trunk directory with
60the -d option plus any of the options or arguments you would normally pass to
61ninja (see descriptions of some of the other flags here).
62
63    export ANDROID_SDK_ROOT=/path/to/android/sdk
64    export PATH=$PATH:/path/to/depot_tools
65
66    cd skia
67    ./platform_tools/android/bin/android_ninja -d nexus_10 # or nexus_7, galaxy_nexus, etc...
68
69The -d option enables the build system to target the build to a specific
70architecture such as MIPS (generic), x86 (generic) and ARM (generic and device
71specific flavors for Nexus devices). This in turn allows Skia to take
72advantage of specific device optimizations (e.g. NEON instructions).
73
74Generate build file from GYP
75----------------------------
76
77We use the open-source gyp tool to generate build files from our multiplatform
78"gyp" files. While most other platforms enable you to regenerate these files
79using `./gyp_skia` it is recommend that you do NOT do this for Android.  Instead
80you can rely on 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
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 (similiar 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
151params...
152
153    --resourcePath /data/local/tmp/skia_resoures
154    --pictureDir /data/local/tmp/skia_skp
155
156Build tools
157-----------
158
159The Android platform does not support skdiff at this time.
160
161Clean up all generated files
162----------------------------
163
164    make clean
165
166Debugging on Android
167--------------------
168
169We support 2 modes of debugging on Android using GDB wrapper scripts. These
170scripts start a gdbserver instance on the device and then enter an interactive
171GDB client shell on your host. All necessary symbol files should
172be pulled from the device and placed into a temporary folder (android_gdb_tmp).
173
174Note: The debugging scripts do not build the app - you'll have to do that first.
175
176    # COMMAND LINE APPS
177    # include additional arguments in quotes (e.g. "dm --nopdf")
178    ./platform_tools/android/bin/android_gdb_native dm
179
180    # SAMPLE APP
181    # make sure you've installed the app on the device first
182    ./platform_tools/android/bin/android_gdb_app
183
184When the gdb client is ready, insert a breakpoint, and continue to let the
185program resume execution.
186
187