1 The `android` module provides support for the Android platform
3 # Compilation for Android
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.
9 # Host system configuration
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.
14 # Configure your Android application
16 The `app.nit` framework and this project offers some services to
17 customized the generated Android application.
21 * `app_version` specifies the version of the generated APK file.
22 It takes 3 arguments: the major, minor and revision version numbers.
23 The special function `git_revision` will use the prefix of the hash of the
24 latest git commit. The default version is 1.0.
26 Example: `app_version(1, 0, git_revision)`
28 * `app_name` takes a single argument, the visible name of the Android
29 application. By default, the compiler would use the name of the target
30 module. This name will be used as the name of the main activity and
33 Example: `app_name "My App"`
35 * `java_package` specifies the package used by the generated Java
36 classes and the APK file. Once the application is published, this
37 value should not be changed. By default, the compiler will use
38 the package `org.nitlanguage.{module_name}`.
40 * Custom information can be added to the Android manifest file
41 using the annotations `android_manifest`, `android_manifest_application`
42 and `android_manifest_activity`.
44 Example usage to specify an extra permission:
47 android_manifest """<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>"""
50 * The API version target can be specified with `min_api_version`,
51 `max_api_version` and `target_api_version`. These take a single
52 integer as argument. They are applied in the Android manifest as
53 `minSdkVesion`, `targetSdkVersion` and `maxSdkVersion`.
55 See http://developer.android.com/guide/topics/manifest/uses-sdk-element.html
57 * The annotation `android_activity` defines a Java class used as an
58 entrypoint to your application. As of now, this annotation should
59 only be used by low level implementations of Nit on Android.
60 It's usefulness will be extended in the future to customize user applications.
62 ## Project entry points
64 Importing `android::landscape` or `android::portrait` locks the generated
65 application in the specified orientation. This can be useful for games and
66 other multimedia applications.
70 There are two compilation modes for the Android platform, debug and release.
71 Theses modes are also applied to the generated Android projects.
72 The compilation mode is specified as an argument to `nitc`, only
73 `--release` can be specified as debug is the default behavior.
77 Debug mode enables compiling to an APK file without handling signing keys
78 and their password. The APK file can be installed to a local device with
79 USB debugging enabled, but it cannot be published on the Play Store.
81 By default, `nitc` will compile Android applications in debug mode.
85 Building in release mode will use your private key to sign the
86 APK file, it can then be published on the Play Store.
88 1. Have a keystore with a valid key to sign your APK file.
90 To create a new keystore, avoid using the default values of `jarsigner`
91 as they change between versions of the Java SDK. You should instead use a
92 command similar to the following, replacing `KEYSTORE_PATH` and `KEY_ALIAS`
93 with the desired values.
96 keytool -genkey -keystore KEYSTORE_PATH -alias KEY_ALIAS -sigalg MD5withRSA -keyalg RSA -keysize 1024 -validity 10000
99 2. Set the environment variables used by `nitc`: `KEYSTORE`, `KEY_ALIAS` and
100 optionally `TSA_SERVER`. These settings can be set in a startup script such as
101 `~/.bashrc` or in a local Makefile.
103 You can use the following commands by replacing the right hand values
104 to your own configuration.
107 export KEYSTORE=keystore_path
108 export KEY_ALIAS=key_alias
109 export TSA_SERVER=timestamp_authority_server_url # Optional
112 3. Call `nitc` with the `--release` options. You will be prompted for the
113 required passwords as needed by `jarsigner`.