lib/android/README.md

   1 The `android` module provides support for the Android platform
   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 for Android, you must install the Android SDK and NDK.
  12 The tools `android`, `ndk-build` and `ant` must be in your PATH.
  13
  14 # Configure your Android application
  15
  16 The _app.nit_ framework and this project offers some services to
  17 customize the generated Android application.
  18
  19 ## Annotations
  20
  21 * All _app.nit_ annotations are applied to Android projects:
  22   `app_name`, `app_namespace` and `app_version`.
  23
  24     See: `../app/README.md`
  25
  26 * Custom information can be added to the Android manifest file
  27 using the annotations `android_manifest`, `android_manifest_application`
  28 and `android_manifest_activity`.
  29
  30     Example usage to specify an extra permission:
  31
  32     ~~~
  33     android_manifest """<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>"""
  34     ~~~
  35
  36 * The API version target can be specified with `android_api_min`,
  37 `android_api_max` and `android_api_target`. These take a single
  38 integer as argument. They are applied in the Android manifest as
  39 `minSdkVesion`, `targetSdkVersion` and `maxSdkVersion`.
  40
  41     See http://developer.android.com/guide/topics/manifest/uses-sdk-element.html
  42
  43 * The annotation `android_activity` defines a Java class used as an
  44   entrypoint to your application. As of now, this annotation should
  45   only be used by low level implementations of Nit on Android.
  46   It's usefulness will be extended in the future to customize user applications.
  47
  48 ## Project entry points
  49
  50 Importing `android::landscape` or `android::portrait` locks the generated
  51 application in the specified orientation. This can be useful for games and
  52 other multimedia applications.
  53
  54 # Compilation modes
  55
  56 There are two compilation modes for the Android platform, debug and release.
  57 Theses modes are also applied to the generated Android projects.
  58 The compilation mode is specified as an argument to `nitc`, only
  59 `--release` can be specified as debug is the default behavior.
  60
  61 ## Debug mode
  62
  63 Debug mode enables compiling to an APK file without handling signing keys
  64 and their password. The APK file can be installed to a local device with
  65 USB debugging enabled, but it cannot be published on the Play Store.
  66
  67 By default, `nitc` will compile Android applications in debug mode.
  68
  69 ## Release mode
  70
  71 Building in release mode will use your private key to sign the
  72 APK file, it can then be published on the Play Store.
  73
  74 1. Have a keystore with a valid key to sign your APK file.
  75
  76     To create a new keystore, avoid using the default values of `jarsigner`
  77 as they change between versions of the Java SDK. You should instead use a
  78 command similar to the following, replacing `KEYSTORE_PATH` and `KEY_ALIAS`
  79 with the desired values.
  80
  81     ~~~
  82     keytool -genkey -keystore KEYSTORE_PATH -alias KEY_ALIAS -sigalg MD5withRSA -keyalg RSA -keysize 1024 -validity 10000
  83     ~~~
  84
  85 2. Set the environment variables used by `nitc`: `KEYSTORE`, `KEY_ALIAS` and
  86 optionally `TSA_SERVER`. These settings can be set in a startup script such as
  87 `~/.bashrc` or in a local Makefile.
  88
  89     You can use the following commands by replacing the right hand values
  90 to your own configuration.
  91
  92     ~~~
  93     export KEYSTORE=keystore_path
  94     export KEY_ALIAS=key_alias
  95     export TSA_SERVER=timestamp_authority_server_url # Optional
  96     ~~~
  97
  98 3. Call `nitc` with the `--release` options. You will be prompted for the
  99 required passwords as needed by `jarsigner`.