Merge pull request #2737 from sigmabeta/android-how-to

Android: Improve build instructions, fix bugs in build scripts.

6 files changed, 113 insertions, 21 deletions

diff --git a/AndroidSetup.md b/AndroidSetup.md
new file mode 100644
index 0000000000..5dfa85d5a9
--- /dev/null
+++ b/AndroidSetup.md
@@ -0,0 +1,68 @@
+# How to Set Up an Android Development Environment
+
+If you'd like to contribute to the Android project, but do not currently have a development environment setup, follow the instructions in this guide.
+
+## Prerequisites
+
+* A Linux VM or host, or a Mac.
+* JDK 7 for your platform.
+* CMake
+* [Android NDK](https://developer.android.com/tools/sdk/ndk/index.html) 
+* [Android Studio](http://developer.android.com/tools/studio/index.html) **OR**
+* [Android SDK Tools](http://developer.android.com/sdk/index.html#Other) (for command-line usage)
+
+If you downloaded Android Studio, extract it and then see [Setting up Android Studio](#setting-up-android-studio).
+
+If you instead chose to download the commoand-line SDK tools, see [Setting up the SDK Tools](#setting-up-the-sdk-tools).
+
+## Setting up Android Studio
+
+1. Launch Android Studio, which will start a first-launch wizard.
+2. Choose a custom installation.
+3. If offered a choice of themes, select your preference.
+4. When offered a choice of components, uncheck the "Android Virtual Device" option. ![Android Studio Components][components]
+5. Accept all licenses, and click Finish. Android Studio will download the SDK Tools package automatically. (Ubuntu users, if you get an error running the `mksdcard` tool, make sure the `lib32stdc++6` package is installed.)
+6. At the Android Studio welcome screen, click "Configure", then "SDK Manager".
+7. Use the SDK Manager to get necessary dependencies, as described in [Getting Dependencies](#getting-dependencies).
+8. When done, follow the steps in [Readme.md](Readme.md#installation-on-android) to compile and deploy the application.
+
+## Setting up the SDK Tools
+
+1. In `Source/Android`, create a file called `local.properties`.
+2. Add a single line: `sdk.dir=<sdk-path>`, where `<sdk-path>` is the path where you extracted the SDK Tools package.
+3. Follow the steps in [Readme.md](Readme.md#installation-on-android) to compile and deploy the application.
+
+## Executing Gradle Tasks
+
+In Android Studio, you can find a list of possible Gradle tasks in a tray at the top right of the screen:
+
+![Gradle Tasks][gradle]
+
+Double clicking any of these tasks will execute it, and also add it to a short list in the main toolbar:
+
+![Gradle Task Shortcuts][shortcut]
+
+Clicking the green triangle next to this list will execute the currently selected task.
+
+For command-line users, any task may be executed with `Source/Android/gradlew <task-name>`.
+
+## Getting Dependencies
+
+Most dependencies for the Android project are supplied by Gradle automatically. However, Android platform libraries (and a few Google-supplied supplementary libraries) must be downloaded through the Android package manager.
+
+1. Launch the Android SDK Manager from the commandline by executing `<sdk-path>/tools/android`, or by clicking on its icon in Android Studio's main toolbar:
+![Android Studio Package Icon][package-icon]
+2. At the bottom of the window, click "Deselect All", and then "Updates".
+3. Install or update the following packages:
+
+* SDK Platform, under "Android 5.0.1 (API 21)". This will allow compiling apps that target Lollipop.
+* Android Support Repository
+* Android Support Library
+* Google Repository
+
+In the future, if the project targets a newer version of Android, or use newer versions of the tools/build-tools packages, it will be necessary to use this tool to download updates.
+
+[components]: http://i.imgur.com/Oo1Fs93.png
+[package-icon]: http://i.imgur.com/NUpkAH8.png
+[gradle]: http://i.imgur.com/dXIH6o3.png
+[shortcut]: http://i.imgur.com/eCWP4Yy.png
\ No newline at end of file
diff --git a/Readme.md b/Readme.md
index 81fe9a38c4..a2fbc3f576 100644
--- a/Readme.md
+++ b/Readme.md
@@ -50,29 +50,37 @@ On OS X, an application bundle will be created in `./Binaries`.
 On Linux, it's strongly recommended to perform a global installation via `sudo make install`.
 
 ## Installation on Android
-Dolphin requires [Android Studio](http://developer.android.com/tools/studio/index.html) to build
-the Android UI. Import the Gradle project located in `./Source/Android`, and then execute the
-Gradle task `assembleDebug` to build, or `installDebug` to install the UI onto a connected device.
 
-In order to launch the app, you must build and include the native Dolphin libraries into the UI project.
-(Building native code requires the [Android NDK](https://developer.android.com/tools/sdk/ndk/index.html).)
-Android Studio will do this for you if you create `Source/Android/build.properties`, and place the
-following inside:
+These instructions assume familiarity with Android development. If you do not have an
+Android dev environment set up, see [AndroidSetup.md](AndroidSetup.md).
+
+If using Android Studio, import the Gradle project located in `./Source/Android`. 
+
+Android apps are compiled using a build system called Gradle. Dolphin's native component,
+however, is compiled using CMake. The Gradle script will attempt to run a CMake build
+automatically while building the Java code, if you create the file `Source/Android/build.properties`,
+and place the following inside:
 
 ```
-makeArgs=<make-args>
+# Specifies arguments for the 'make' command. Can be blank.
+makeArgs=
+
+# The path to your machine's Git executable. Will autodetect if blank (on Linux only).
+gitPath=
+
+# The path to the CMake executable. Will autodetect if blank (on Linux only).
+cmakePath=
+
+# The path to the extracted NDK package. Will autodetect if blank (on Linux only).
+ndkPath=
 ```
 
-Replace `<make-args>` with any arguments you want to pass to `make`. If you need to use a specific
-version of git, cmake, or the NDK, you can also add `gitPath=<path>`, `cmakePath=<path>` or
-`ndkPath=<path>`, replacing `<path>` with the actual paths. Otherwise, these will be found
-automatically. Then execute the `assembleDebug` or `installDebug` task corresponding to the
-hardware platform you are targeting. For example, to deploy to a Nexus 9, which runs the AArch64
-architecture, execute `installArm_64Debug`. A list of available tasks can be found in Android
-Studio in the Gradle tray, located at the top-right corner of the IDE by default.
+If you prefer, you can run the CMake step manually, and it will copy the resulting
+binary into the correct location for inclusion in the Android APK.
 
-The native libraries will be compiled, and copied into `./Source/Android/app/libs`. Android Studio
-and Gradle will include any libraries in that folder into the APK at build time.
+Execute the Gradle task `assembleArm_64Debug` to build, or `installArm_64Debug` to
+install the application onto a connected device. If other ABIs are eventually supported,
+execute the tasks corresponding to the desired ABI.
 
 ## Uninstalling
 When Dolphin has been installed with the NSIS installer, you can uninstall
diff --git a/Source/Android/.gitignore b/Source/Android/.gitignore
index a053548512..3fbf1ea2ff 100644
--- a/Source/Android/.gitignore
+++ b/Source/Android/.gitignore
@@ -36,7 +36,6 @@ workspace.xml
 tasks.xml
 .gradle/*
 .idea
-gradle/
 build/
 *.so
 *.iml
diff --git a/Source/Android/app/build.gradle b/Source/Android/app/build.gradle
index b936e0604d..8f5ce60a76 100644
--- a/Source/Android/app/build.gradle
+++ b/Source/Android/app/build.gradle
@@ -134,7 +134,11 @@ task compileNative(type: Exec, dependsOn: 'setupCMake') {
 
         executable 'make'
 
-        args buildProperties.makeArgs
+        if (buildProperties.makeArgs == null || buildProperties.makeArgs.isEmpty()) {
+            // TODO
+        } else {
+            args buildProperties.makeArgs
+        }
     } else {
         executable 'echo'
         args 'No build.properties found; skipping native build.'
@@ -144,13 +148,15 @@ task compileNative(type: Exec, dependsOn: 'setupCMake') {
 String getExecutablePath(String command) {
     def propsFile = rootProject.file("build.properties")
     def path = null
+
     if (propsFile.canRead()) {
         def buildProperties = new Properties()
         buildProperties.load(new FileInputStream(propsFile))
         println buildProperties
         path = buildProperties[command + "Path"]
     }
-    if (path == null) {
+
+    if (path == null || path.isEmpty()) {
         try {
             def stdout = new ByteArrayOutputStream()
 
@@ -164,21 +170,25 @@ String getExecutablePath(String command) {
             project.logger.error("Gradle error: Couldn't find " + command + " executable.")
         }
     }
+
     if (path != null) {
         project.logger.quiet("Gradle: Found " + command + " executuable:" + path)
     }
+
     return path
 }
 
 String getNdkPath() {
     def propsFile = rootProject.file("build.properties")
     def ndkPath = null
+
     if (propsFile.canRead()) {
         def buildProperties = new Properties()
         buildProperties.load(new FileInputStream(propsFile))
         ndkPath = buildProperties.ndkPath
     }
-    if (ndkPath == null) {
+
+    if (ndkPath == null || ndkPath.isEmpty()) {
         try {
             def stdout = new ByteArrayOutputStream()
 
@@ -194,6 +204,7 @@ String getNdkPath() {
             project.logger.error("Gradle error: Couldn't find NDK.")
         }
     }
+
     if (ndkPath != null) {
         project.logger.quiet("Gradle: Found Android NDK: " + ndkPath)
     }
diff --git a/Source/Android/gradle/wrapper/gradle-wrapper.jar b/Source/Android/gradle/wrapper/gradle-wrapper.jar
new file mode 100644
index 0000000000..8c0fb64a86
--- /dev/null
+++ b/Source/Android/gradle/wrapper/gradle-wrapper.jar
diff --git a/Source/Android/gradle/wrapper/gradle-wrapper.properties b/Source/Android/gradle/wrapper/gradle-wrapper.properties
new file mode 100644
index 0000000000..0c71e760dc
--- /dev/null
+++ b/Source/Android/gradle/wrapper/gradle-wrapper.properties
@@ -0,0 +1,6 @@
+#Wed Apr 10 15:27:10 PDT 2013
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-2.2.1-all.zip