android: update host setup guide

[nit.git] / lib / android / README.md

diff --git a/lib/android/README.md b/lib/android/README.md
index 50ac38d..457f426 100644 (file)
--- a/lib/android/README.md
+++ b/lib/android/README.md
@@ -8,10 +8,52 @@ file can be specified using the `-o` and `--dir` options.
 
 # Host system configuration
 
-To compile for Android, you must install the Android SDK and NDK.
-The tools `android`, `ndk-build` and `ant` must be in your PATH.
+To compile Android apps from a 64 bits GNU/Linux host you can reuse an existing Android Studio
+installation or make a clean install with command line tools only.
 
-# Configure your Android application
+Note that this guide supports only 64 bits GNU/Linux hosts with support for a Java 8 JDK,
+it may be possible to support other platforms with some tweaks.
+
+1.     Install the required SDK packages using one of these two methods:
+
+       a.      Using Android Studio, open `Tools > Android > SDK Manager`, in the SDK Tools tab,
+               install "Android SDK Build-Tools", CMake and NDK.
+
+       b.      From the command line, run this script for a quick setup without Android Studio.
+               You will probably need to tweak it to you system or update the download URL
+               to the latest SDK tools from https://developer.android.com/studio/index.html#command-tools
+
+               ~~~
+               # Fetch and extract SDK tools
+               mkdir -p ~/Android/Sdk
+               cd ~/Android/Sdk
+               wget https://dl.google.com/android/repository/sdk-tools-linux-3859397.zip
+               unzip sdk-tools-linux-3859397.zip
+
+               # Update tools
+               tools/bin/sdkmanager --update
+
+               # Accept the licenses
+               tools/bin/sdkmanager --licenses
+
+               # Install the basic build tools
+               tools/bin/sdkmanager "build-tools;27.0.0" ndk-bundle
+               ~~~
+
+3.     Set the environment variable ANDROID_HOME to the SDK installation directory, usually `~/Android/Sdk/`.
+       Use the following command to setup the variable for bash.
+
+       ~~~
+       echo "export ANDROID_HOME=~/Android/Sdk/" >> ~/.bashrc
+       ~~~
+
+4.     Install Java 8 JDK, on Debian/Ubuntu systems you can use the following command:
+
+       ~~~
+       sudo apt install openjdk-8-jdk
+       ~~~
+
+# Configure the Android application
 
 The _app.nit_ framework and this project offers some services to
 customize the generated Android application.
@@ -41,11 +83,20 @@ integer as argument. They are applied in the Android manifest as
     See http://developer.android.com/guide/topics/manifest/uses-sdk-element.html
 
 * The annotation `android_activity` defines a Java class used as an
-  entrypoint to your application. As of now, this annotation should
-  only be used by low level implementations of Nit on Android.
-  It's usefulness will be extended in the future to customize user applications.
+ entry point to your application. As of now, this annotation should
+  only be used by low-level implementations of Nit on Android.
+  Its usefulness will be extended in the future to customize user applications.
+
+## Android implementation
+
+There is two core implementation for Nit apps on Android.
+`android::nit_activity` is used by apps with standard windows and native UI controls.
+`android::game` is used by, well, games and the game frameworks `mnit` and `gamnit`.
+
+Clients don't have to select the core implementation, it is imported by other relevant modules.
+For example, a module importing `app::ui` and `android` will trigger the importation of `android::nit_activity`.
 
-## Project entry points
+## Lock app orientation
 
 Importing `android::landscape` or `android::portrait` locks the generated
 application in the specified orientation. This can be useful for games and
@@ -86,7 +137,7 @@ with the desired values.
 optionally `TSA_SERVER`. These settings can be set in a startup script such as
 `~/.bashrc` or in a local Makefile.
 
-    You can use the following commands by replacing the right hand values
+    You can use the following commands by replacing the right-hand values
 to your own configuration.
 
     ~~~