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 Some configuration is required to compile for the Android platform from a GNU/Linux host.
  12
  13 1. Download and install the latest Android SDK __and__ NDK.
  14
  15 2. Update PATH so it includes the tools `android`, `ndk-build` and `ant`.
  16         You should add something like the following snippet to your .bashrc or equivalent,
  17         be careful to replace `ANDROID_SDK` and `ANDROID_NDK` with the full path where you installed each package.
  18
  19         ~~~
  20         export PATH=$PATH:ANDROID_SDK/tools/:ANDROID_SDK/platform-tools/:ANDROID_NDK/
  21         ~~~
  22
  23 2. Using the `android` executable, download the latest `tools, build-tools` and within the Android 4.0.3 (API 15) folder, install `SDK platform`.
  24         You may have to install additional SDK platforms for applications with different targets.
  25
  26 3. Using your OS package manager, install `apt openjdk-7-jdk lib32stdc++6 lib32z1`.
  27         On Debian and Ubuntu the command is:
  28
  29         ~~~
  30         sudo apt-get install apt openjdk-7-jdk lib32stdc++6 lib32z1
  31         ~~~
  32
  33 # Configure your Android application
  34
  35 The _app.nit_ framework and this project offers some services to
  36 customize the generated Android application.
  37
  38 ## Annotations
  39
  40 * All _app.nit_ annotations are applied to Android projects:
  41   `app_name`, `app_namespace` and `app_version`.
  42
  43     See: `../app/README.md`
  44
  45 * Custom information can be added to the Android manifest file
  46 using the annotations `android_manifest`, `android_manifest_application`
  47 and `android_manifest_activity`.
  48
  49     Example usage to specify an extra permission:
  50
  51     ~~~
  52     android_manifest """<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>"""
  53     ~~~
  54
  55 * The API version target can be specified with `android_api_min`,
  56 `android_api_max` and `android_api_target`. These take a single
  57 integer as argument. They are applied in the Android manifest as
  58 `minSdkVesion`, `targetSdkVersion` and `maxSdkVersion`.
  59
  60     See http://developer.android.com/guide/topics/manifest/uses-sdk-element.html
  61
  62 * The annotation `android_activity` defines a Java class used as an
  63  entry point to your application. As of now, this annotation should
  64   only be used by low-level implementations of Nit on Android.
  65   Its usefulness will be extended in the future to customize user applications.
  66
  67 ## Android implementation
  68
  69 There is two core implementation for Nit apps on Android.
  70 `android::nit_activity` is used by apps with standard windows and native UI controls.
  71 `android::game` is used by, well, games and the game frameworks `mnit` and `gamnit`.
  72
  73 Clients don't have to select the core implementation, it is imported by other relevant modules.
  74 For example, a module importing `app::ui` and `android` will trigger the importation of `android::nit_activity`.
  75
  76 ## Lock app orientation
  77
  78 Importing `android::landscape` or `android::portrait` locks the generated
  79 application in the specified orientation. This can be useful for games and
  80 other multimedia applications.
  81
  82 # Compilation modes
  83
  84 There are two compilation modes for the Android platform, debug and release.
  85 Theses modes are also applied to the generated Android projects.
  86 The compilation mode is specified as an argument to `nitc`, only
  87 `--release` can be specified as debug is the default behavior.
  88
  89 ## Debug mode
  90
  91 Debug mode enables compiling to an APK file without handling signing keys
  92 and their password. The APK file can be installed to a local device with
  93 USB debugging enabled, but it cannot be published on the Play Store.
  94
  95 By default, `nitc` will compile Android applications in debug mode.
  96
  97 ## Release mode
  98
  99 Building in release mode will use your private key to sign the
 100 APK file, it can then be published on the Play Store.
 101
 102 1. Have a keystore with a valid key to sign your APK file.
 103
 104     To create a new keystore, avoid using the default values of `jarsigner`
 105 as they change between versions of the Java SDK. You should instead use a
 106 command similar to the following, replacing `KEYSTORE_PATH` and `KEY_ALIAS`
 107 with the desired values.
 108
 109     ~~~
 110     keytool -genkey -keystore KEYSTORE_PATH -alias KEY_ALIAS -sigalg MD5withRSA -keyalg RSA -keysize 1024 -validity 10000
 111     ~~~
 112
 113 2. Set the environment variables used by `nitc`: `KEYSTORE`, `KEY_ALIAS` and
 114 optionally `TSA_SERVER`. These settings can be set in a startup script such as
 115 `~/.bashrc` or in a local Makefile.
 116
 117     You can use the following commands by replacing the right-hand values
 118 to your own configuration.
 119
 120     ~~~
 121     export KEYSTORE=keystore_path
 122     export KEY_ALIAS=key_alias
 123     export TSA_SERVER=timestamp_authority_server_url # Optional
 124     ~~~
 125
 126 3. Call `nitc` with the `--release` options. You will be prompted for the
 127 required passwords as needed by `jarsigner`.