lib/android/README.md

   1 Android platform support and APIs
   2
   3 # Compilation for Android
   4
   5 The compiler generates an APK file as the output when the `android`
   6 module is imported by the compilation target. The path to the generated
   7 file can be specified using the `-o` and `--dir` options.
   8
   9 # Host system configuration
  10
  11 To compile Android apps from a 64 bits GNU/Linux host you can reuse an existing Android Studio
  12 installation or make a clean install with command line tools only.
  13
  14 Note that this guide supports only 64 bits GNU/Linux hosts with support for a Java 8 JDK,
  15 it may be possible to support other platforms with some tweaks.
  16
  17 1.      Install the required SDK packages using one of these two methods:
  18
  19         a.      Using Android Studio, open `Tools > Android > SDK Manager`, in the SDK Tools tab,
  20                 install "Android SDK Build-Tools", CMake and NDK.
  21
  22         b.      From the command line, run this script for a quick setup without Android Studio.
  23                 You will probably need to tweak it to you system or update the download URL
  24                 to the latest SDK tools from https://developer.android.com/studio/index.html#command-tools
  25
  26                 ~~~
  27                 # Fetch and extract SDK tools
  28                 mkdir -p ~/Android/Sdk
  29                 cd ~/Android/Sdk
  30                 wget https://dl.google.com/android/repository/sdk-tools-linux-3859397.zip
  31                 unzip sdk-tools-linux-3859397.zip
  32
  33                 # Update tools
  34                 tools/bin/sdkmanager --update
  35
  36                 # Accept the licenses
  37                 tools/bin/sdkmanager --licenses
  38
  39                 # Install the basic build tools
  40                 tools/bin/sdkmanager "build-tools;27.0.0" ndk-bundle
  41                 ~~~
  42
  43 3.      Set the environment variable ANDROID_HOME to the SDK installation directory, usually `~/Android/Sdk/`.
  44         Use the following command to setup the variable for bash.
  45
  46         ~~~
  47         echo "export ANDROID_HOME=~/Android/Sdk/" >> ~/.bashrc
  48         ~~~
  49
  50 4.      Install Java 8 JDK, on Debian/Ubuntu systems you can use the following command:
  51
  52         ~~~
  53         sudo apt install openjdk-8-jdk
  54         ~~~
  55
  56 # Configure the Android application
  57
  58 The _app.nit_ framework and this project offers some services to
  59 customize the generated Android application.
  60
  61 ## Annotations
  62
  63 * All _app.nit_ annotations are applied to Android projects:
  64   `app_name`, `app_namespace` and `app_version`.
  65
  66     See: `../app/README.md`
  67
  68 * Custom information can be added to the Android manifest file
  69 using the annotations `android_manifest`, `android_manifest_application`
  70 and `android_manifest_activity`.
  71
  72     Example usage to specify an extra permission:
  73
  74     ~~~
  75     android_manifest """<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>"""
  76     ~~~
  77
  78 * The API version target can be specified with `android_api_min`,
  79 `android_api_max` and `android_api_target`. These take a single
  80 integer as argument. They are applied in the Android manifest as
  81 `minSdkVesion`, `targetSdkVersion` and `maxSdkVersion`.
  82
  83     See http://developer.android.com/guide/topics/manifest/uses-sdk-element.html
  84
  85 * The annotation `android_activity` defines a Java class used as an
  86  entry point to your application. As of now, this annotation should
  87   only be used by low-level implementations of Nit on Android.
  88   Its usefulness will be extended in the future to customize user applications.
  89
  90 ## Android implementation
  91
  92 There is two core implementation for Nit apps on Android.
  93 `android::nit_activity` is used by apps with standard windows and native UI controls.
  94 `android::game` is used by, well, games and the game frameworks `mnit` and `gamnit`.
  95
  96 Clients don't have to select the core implementation, it is imported by other relevant modules.
  97 For example, a module importing `app::ui` and `android` will trigger the importation of `android::nit_activity`.
  98
  99 ## Lock app orientation
 100
 101 Importing `android::landscape` or `android::portrait` locks the generated
 102 application in the specified orientation. This can be useful for games and
 103 other multimedia applications.
 104
 105 # Compilation modes
 106
 107 There are two compilation modes for the Android platform, debug and release.
 108 Theses modes are also applied to the generated Android projects.
 109 The compilation mode is specified as an argument to `nitc`, only
 110 `--release` can be specified as debug is the default behavior.
 111
 112 ## Debug mode
 113
 114 Debug mode enables compiling to an APK file without handling signing keys
 115 and their password. The APK file can be installed to a local device with
 116 USB debugging enabled, but it cannot be published on the Play Store.
 117
 118 By default, `nitc` will compile Android applications in debug mode.
 119
 120 ## Release mode
 121
 122 Building in release mode will use your private key to sign the
 123 APK file, it can then be published on the Play Store.
 124
 125 1. Have a keystore with a valid key to sign your APK file.
 126
 127     To create a new keystore, avoid using the default values of `jarsigner`
 128 as they change between versions of the Java SDK. You should instead use a
 129 command similar to the following, replacing `KEYSTORE_PATH` and `KEY_ALIAS`
 130 with the desired values.
 131
 132     ~~~
 133     keytool -genkey -keystore KEYSTORE_PATH -alias KEY_ALIAS -sigalg MD5withRSA -keyalg RSA -keysize 1024 -validity 10000
 134     ~~~
 135
 136 2. Set the environment variables used by `nitc`: `KEYSTORE`, `KEY_ALIAS` and
 137 optionally `TSA_SERVER`. These settings can be set in a startup script such as
 138 `~/.bashrc` or in a local Makefile.
 139
 140     You can use the following commands by replacing the right-hand values
 141 to your own configuration.
 142
 143     ~~~
 144     export KEYSTORE=keystore_path
 145     export KEY_ALIAS=key_alias
 146     export TSA_SERVER=timestamp_authority_server_url # Optional
 147     ~~~
 148
 149 3. Call `nitc` with the `--release` options. You will be prompted for the
 150 required passwords as needed by `jarsigner`.