1 Android platform support and APIs
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 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.
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.
17 1. Install the required SDK packages using one of these two methods:
19 a. Using Android Studio, open `Tools > Android > SDK Manager`, in the SDK Tools tab,
20 install "Android SDK Build-Tools", CMake and NDK.
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
27 # Fetch and extract SDK tools
28 mkdir -p ~/Android/Sdk
30 wget https://dl.google.com/android/repository/sdk-tools-linux-3859397.zip
31 unzip sdk-tools-linux-3859397.zip
34 tools/bin/sdkmanager --update
37 tools/bin/sdkmanager --licenses
39 # Install the basic build tools
40 tools/bin/sdkmanager "build-tools;27.0.0" ndk-bundle
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.
47 echo "export ANDROID_HOME=~/Android/Sdk/" >> ~/.bashrc
50 4. Install Java 8 JDK, on Debian/Ubuntu systems you can use the following command:
53 sudo apt install openjdk-8-jdk
56 # Configure the Android application
58 The _app.nit_ framework and this project offers some services to
59 customize the generated Android application.
63 * All _app.nit_ annotations are applied to Android projects:
64 `app_name`, `app_namespace` and `app_version`.
66 See: `../app/README.md`
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`.
72 Example usage to specify an extra permission:
75 android_manifest """<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>"""
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`.
83 See http://developer.android.com/guide/topics/manifest/uses-sdk-element.html
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.
90 ## Android implementation
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`.
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`.
99 ## Lock app orientation
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.
105 ## Resources and application icon
107 Resources specific to the Android platform should be placed in an `android/` folder at the root of the project.
108 The folder should adopt the structure of a normal Android project, e.g., a custom XML resource file can be placed
109 at `android/res/values/color.xml` to be compiled with the Android application.
111 The application icon should also be placed in the `android/` folder.
112 Place the classic bitmap version at `android/res/mipmap-hdpi/ic_launcher.png` (and others),
113 and the adaptive version at `android/res/mipmap-anydpi-v26/ic_launcher.xml`.
114 The Nit compiler detects these files and uses them as the application icon.
116 Additional `android/` folders may be placed next to more specific Nit modules to change the Android resources
117 for application variants. The more specific resources will have priority over the project level `android/` files.
121 There are two compilation modes for the Android platform, debug and release.
122 Theses modes are also applied to the generated Android projects.
123 The compilation mode is specified as an argument to `nitc`, only
124 `--release` can be specified as debug is the default behavior.
128 Debug mode enables compiling to an APK file without handling signing keys
129 and their password. The APK file can be installed to a local device with
130 USB debugging enabled, but it cannot be published on the Play Store.
132 By default, `nitc` will compile Android applications in debug mode.
136 Building in release mode will use your private key to sign the
137 APK file, it can then be published on the Play Store.
139 1. Have a keystore with a valid key to sign your APK file.
141 To create a new keystore, avoid using the default values of `jarsigner`
142 as they change between versions of the Java SDK. You should instead use a
143 command similar to the following, replacing `KEYSTORE_PATH` and `KEY_ALIAS`
144 with the desired values.
147 keytool -genkey -keystore KEYSTORE_PATH -alias KEY_ALIAS -sigalg MD5withRSA -keyalg RSA -keysize 1024 -validity 10000
150 2. Set the environment variables used by `nitc`: `KEYSTORE`, `KEY_ALIAS` and
151 optionally `TSA_SERVER`. These settings can be set in a startup script such as
152 `~/.bashrc` or in a local Makefile.
154 You can use the following commands by replacing the right-hand values
155 to your own configuration.
158 export KEYSTORE=keystore_path
159 export KEY_ALIAS=key_alias
160 export TSA_SERVER=timestamp_authority_server_url # Optional
163 3. Call `nitc` with the `--release` options. You will be prompted for the
164 required passwords as needed by `jarsigner`.