From: Alexis Laferrière Date: Sat, 10 Jan 2015 14:23:13 +0000 (-0500) Subject: lib/android: add a README file to the project X-Git-Tag: v0.7.1~36^2 X-Git-Url: http://nitlanguage.org lib/android: add a README file to the project Signed-off-by: Alexis Laferrière --- diff --git a/lib/android/README.md b/lib/android/README.md new file mode 100644 index 0000000..1f4e659 --- /dev/null +++ b/lib/android/README.md @@ -0,0 +1,108 @@ +The `android` module provides support for the Android platform + +# Compilation for Android + +The compiler generates an APK file as the output when the `android` +module is imported by the compilation target. The path to the generated +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. + +# Configure your Android application + +The `app.nit` framework and this project offers some services to +customized the generated Android application. + +## Module annotations + +* `app_version` specifies the version of the generated APK file. +It takes 3 arguments: the major, minor and revision version numbers. +The special function `git_revision` will use the prefix of the hash of the +latest git commit. The default version is 1.0. + + Example: `app_version(1, 0, git_revision)` + +* `app_name` takes a single argument, the visible name of the Android +application. By default, the compiler would use the name of the target +module. This name will be used as the name of the main activity and +as the launcher name. + + Example: `app_name "My App"` + +* `java_package` specifies the package used by the generated Java +classes and the APK file. Once the application is published, this +value should not be changed. By default, the compiler will use +the package `org.nitlanguage.{module_name}`. + +* Custom information can be added to the Android manifest file +using the annotations `android_manifest`, `android_manifest_application` +and `android_manifest_activity`. + + Example usage to specify an extra permission: + + ~~~ + android_manifest """""" + ~~~ + +* The API version target can be specified with `min_api_version`, +`max_api_version` and `target_api_version`. These take a single +integer as argument. They are applied in the Android manifest as +`minSdkVesion`, `targetSdkVersion` and `maxSdkVersion`. + + See http://developer.android.com/guide/topics/manifest/uses-sdk-element.html + +## Project entry points + +Importing `android::landscape` or `android::portrait` locks the generated +application in the specified orientation. This can be useful for games and +other multimedia applications. + +# Compilation modes + +There are two compilation modes for the Android platform, debug and release. +Theses modes are also applied to the generated Android projects. +The compilation mode is specified as an argument to `nitc`, only +`--release` can be specified as debug is the default behavior. + +## Debug mode + +Debug mode enables compiling to an APK file without handling signing keys +and their password. The APK file can be installed to a local device with +USB debugging enabled, but it cannot be published on the Play Store. + +By default, `nitc` will compile Android applications in debug mode. + +## Release mode + +Building in release mode will use your private key to sign the +APK file, it can then be published on the Play Store. + +1. Have a keystore with a valid key to sign your APK file. + + To create a new keystore, avoid using the default values of `jarsigner` +as they change between versions of the Java SDK. You should instead use a +command similar to the following, replacing `KEYSTORE_PATH` and `KEY_ALIAS` +with the desired values. + + ~~~ + keytool -genkey -keystore KEYSTORE_PATH -alias KEY_ALIAS -sigalg MD5withRSA -keyalg RSA -keysize 1024 -validity 10000 + ~~~ + +2. Set the environment variables used by `nitc`: `KEYSTORE`, `KEY_ALIAS` and +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 +to your own configuration. + + ~~~ + export KEYSTORE=keystore_path + export KEY_ALIAS=key_alias + export TSA_SERVER=timestamp_authority_server_url # Optional + ~~~ + +3. Call `nitc` with the `--release` options. You will be prompted for the +required passwords as needed by `jarsigner`. diff --git a/lib/android/android.nit b/lib/android/android.nit index 5523f30..584b89b 100644 --- a/lib/android/android.nit +++ b/lib/android/android.nit @@ -16,10 +16,6 @@ # Android services and implementation of app.nit # -# To use this module and compile for Android, you must install the -# Android SDK (with API level 10) and NDK (with the API level 9). -# The tools `android`, `ndk-build` and `ant` must be in your PATH. -# # This module provides basic logging facilities, advanced logging can be # achieved by importing `android::log`. module android