-The `android` module provides support for the Android platform
+Android platform support and APIs
# Compilation for Android
# 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.
+To compile Android apps from a 64 bits GNU/Linux host you can reuse an existing Android Studio
+installation or make a clean install with command line tools only.
-# Configure your Android application
+Note that this guide supports only 64 bits GNU/Linux hosts with support for a Java 8 JDK,
+it may be possible to support other platforms with some tweaks.
-The `app.nit` framework and this project offers some services to
-customized the generated Android application.
+1. Install the required SDK packages using one of these two methods:
-## Module annotations
+ a. Using Android Studio, open `Tools > Android > SDK Manager`, in the SDK Tools tab,
+ install "Android SDK Build-Tools", CMake and NDK.
-* `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.
+ b. From the command line, run this script for a quick setup without Android Studio.
+ You will probably need to tweak it to you system or update the download URL
+ to the latest SDK tools from https://developer.android.com/studio/index.html#command-tools
- Example: `app_version(1, 0, git_revision)`
+ ~~~raw
+ # Fetch and extract SDK tools
+ mkdir -p ~/Android/Sdk
+ cd ~/Android/Sdk
+ wget https://dl.google.com/android/repository/sdk-tools-linux-3859397.zip
+ unzip sdk-tools-linux-3859397.zip
-* `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.
+ # Update tools
+ tools/bin/sdkmanager --update
- Example: `app_name "My App"`
+ # Accept the licenses
+ tools/bin/sdkmanager --licenses
-* `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}`.
+ # Install the basic build tools
+ tools/bin/sdkmanager "build-tools;27.0.0" ndk-bundle
+ ~~~
+
+3. Set the environment variable ANDROID_HOME to the SDK installation directory, usually `~/Android/Sdk/`.
+ Use the following command to setup the variable for bash.
+
+ ~~~raw
+ echo "export ANDROID_HOME=~/Android/Sdk/" >> ~/.bashrc
+ ~~~
+
+4. Install Java 8 JDK, on Debian/Ubuntu systems you can use the following command:
+
+ ~~~raw
+ sudo apt install openjdk-8-jdk
+ ~~~
+
+# Configure the Android application
+
+The _app.nit_ framework and this project offers some services to
+customize the generated Android application.
+
+## Annotations
+
+* All _app.nit_ annotations are applied to Android projects:
+ `app_name`, `app_namespace` and `app_version`.
+
+ See: `../app/README.md`
* Custom information can be added to the Android manifest file
using the annotations `android_manifest`, `android_manifest_application`
Example usage to specify an extra permission:
- ~~~
+ ~~~raw
android_manifest """<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>"""
~~~
-* The API version target can be specified with `min_api_version`,
-`max_api_version` and `target_api_version`. These take a single
+* The API version target can be specified with `android_api_min`,
+`android_api_max` and `android_api_target`. 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
+* The annotation `android_activity` defines a Java class used as an
+ entry point to your application. As of now, this annotation should
+ only be used by low-level implementations of Nit on Android.
+ Its usefulness will be extended in the future to customize user applications.
+
+## Android implementation
+
+There is two core implementation for Nit apps on Android.
+`android::nit_activity` is used by apps with standard windows and native UI controls.
+`android::game` is used by, well, games and the game frameworks `mnit` and `gamnit`.
+
+Clients don't have to select the core implementation, it is imported by other relevant modules.
+For example, a module importing `app::ui` and `android` will trigger the importation of `android::nit_activity`.
+
+## Lock app orientation
Importing `android::landscape` or `android::portrait` locks the generated
application in the specified orientation. This can be useful for games and
other multimedia applications.
+## Resources and application icon
+
+Resources specific to the Android platform should be placed in an `android/` folder at the root of the project.
+The folder should adopt the structure of a normal Android project, e.g., a custom XML resource file can be placed
+at `android/res/values/color.xml` to be compiled with the Android application.
+
+The application icon should also be placed in the `android/` folder.
+Place the classic bitmap version at `android/res/mipmap-hdpi/ic_launcher.png` (and others),
+and the adaptive version at `android/res/mipmap-anydpi-v26/ic_launcher.xml`.
+The Nit compiler detects these files and uses them as the application icon.
+
+Additional `android/` folders may be placed next to more specific Nit modules to change the Android resources
+for application variants. The more specific resources will have priority over the project level `android/` files.
+
# Compilation modes
There are two compilation modes for the Android platform, debug and release.
command similar to the following, replacing `KEYSTORE_PATH` and `KEY_ALIAS`
with the desired values.
- ~~~
+ ~~~raw
keytool -genkey -keystore KEYSTORE_PATH -alias KEY_ALIAS -sigalg MD5withRSA -keyalg RSA -keysize 1024 -validity 10000
~~~
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
+ You can use the following commands by replacing the right-hand values
to your own configuration.
- ~~~
+ ~~~raw
export KEYSTORE=keystore_path
export KEY_ALIAS=key_alias
export TSA_SERVER=timestamp_authority_server_url # Optional
nitlanguage / nit.git / blobdiff