Android platform support and APIs

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 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.

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.

  1. Install the required SDK packages using one of these two methods:

    a. Using Android Studio, open Tools > Android > SDK Manager, in the SDK Tools tab,

    install "Android SDK Build-Tools", CMake and NDK.
    

    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
    
    ~~~
    # 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
    
    # Update tools
    tools/bin/sdkmanager --update
    
    # Accept the licenses
    tools/bin/sdkmanager --licenses
    
    # Install the basic build tools
    tools/bin/sdkmanager "build-tools;27.0.0" ndk-bundle
    ~~~
    
  2. Set the environment variable ANDROID_HOME to the SDK installation directory, usually ~/Android/Sdk/. Use the following command to setup the variable for bash.

    echo "export ANDROID_HOME=~/Android/Sdk/" >> ~/.bashrc
    
  3. Install Java 8 JDK, on Debian/Ubuntu systems you can use the following command:

    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 and android_manifest_activity.

    Example usage to specify an extra permission:

    android_manifest """<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>"""
  • 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

  • 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. nit_activity is used by apps with standard windows and native UI controls. 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 ui and android will trigger the importation of nit_activity.

Lock app orientation

Importing landscape or 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. 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.

All groups and modules

module activities

android :: activities

Android Activities wrapper
module android

android :: android

Android services and implementation of app.nit
module assets

android :: assets

Implementation of app::assets
module assets_and_resources

android :: assets_and_resources

Android Assets and Resources Management
module audio

android :: audio

Android audio services, wraps a part of android audio API
module aware

android :: aware

Android compatibility module
group bundle

android > bundle

A mapping class of String to various value types used by the
module cardboard

android :: cardboard

Services from the Google Cardboard SDK for virtual reality on Android
module dalvik

android :: dalvik

Java related services specific to Android and its Dalvik VM
module data_store

android :: data_store

Implements app::data_store using shared_preferences
module game

android :: game

Android services and implementation of app.nit for gamnit and mnit
module gamepad

android :: gamepad

Support for gamepad events (over Bluetooth or USB)
module http_request

android :: http_request

Android implementation of app:http_request
module input_events

android :: input_events

Pointer and hardware key events
group intent

android > intent

Services allowing to launch activities and start/stop services using
module landscape

android :: landscape

Lock the application in the landscape orientation
module load_image

android :: load_image

Low-level services to load pixel data from the assets
module log

android :: log

Advanced Android logging services
module native_app_glue

android :: native_app_glue

Wrapper of the Android native_app_glue framework to implement app.nit
module nit_activity

android :: nit_activity

Core implementation of app.nit on Android using a custom Java entry point
group notification

android > notification

Services to show notification in the Android status bar
module platform

android :: platform

Triggers compilation for the android platform
module portrait

android :: portrait

Config to set the portrait orientation
module sensors

android :: sensors

Access Android sensors
group service

android > service

Android service support for app.nit centered around the class Service
group shared_preferences

android > shared_preferences

Services allowing to save and load datas to internal android device
module toast

android :: toast

Services to display a toast, a small popup on Android
group ui

android > ui

Views and services to use the Android native user interface
module vibration

android :: vibration

Vibration services for Android
module wifi

android :: wifi

Simple wrapper of the Android WiFi services
package_diagram android android java java android->java app app android->app core core android->core mnit mnit android->mnit c c android->c gamnit gamnit android->gamnit json json android->json jvm jvm java->jvm app->core app->json serialization serialization app->serialization pthreads pthreads app->pthreads mnit->core c->core gamnit->app egl egl gamnit->egl ...jvm ... ...jvm->jvm ...core ... ...core->core ...serialization ... ...serialization->serialization ...pthreads ... ...pthreads->pthreads ...json ... ...json->json ...gamnit ... ...gamnit->gamnit egl->android glesv2 glesv2 glesv2->android glesv2->egl ios ios ios->app linux linux linux->app gamnit... ... gamnit...->gamnit ios... ... ios...->ios linux... ... linux...->linux glesv2... ... glesv2...->glesv2

Ancestors

package binary

binary

Read and write binary data with any Reader and Writer
package cocoa

cocoa

Cocoa API, the development layer of OS X
package curl

curl

Data transfer powered by the native curl library
package dom

dom

Easy XML DOM parser
package egl

egl

Interface between rendering APIs (OpenGL, OpenGL ES, etc.) and the native windowing system.
package gen_nit

gen_nit

Support to generate and otherwise manipulate Nit code
package geometry

geometry

Basic geometry data structures and services.
package glesv2

glesv2

OpenGL graphics rendering library for embedded systems, version 2.0
package gtk

gtk

GTK+ widgets and services
package ios

ios

iOS support for app.nit
package jvm

jvm

Java Virtual Machine invocation API and others services from the JNI C API
package linux

linux

Implementation of app.nit for the Linux platform
package matrix

matrix

Services for matrices of Float values
package meta

meta

Simple user-defined meta-level to manipulate types of instances as object.
package more_collections

more_collections

Highly specific, but useful, collections-related classes.
package msgpack

msgpack

MessagePack, an efficient binary serialization format
package opts

opts

Management of options on the command line
package parser_base

parser_base

Simple base for hand-made parsers of all kinds
package performance_analysis

performance_analysis

Services to gather information on the performance of events by categories
package pipeline

pipeline

Pipelined filters and operations on iterators.
package poset

poset

Pre order sets and partial order set (ie hierarchies)
package pthreads

pthreads

POSIX Threads support
package realtime

realtime

Services to keep time of the wall clock time
package sdl2

sdl2

This is a low-level wrapper of the SDL 2.0 library (as sdl2) and SDL_image 2.0 (as sdl2::image).
package serialization

serialization

Abstract serialization services
package socket

socket

Socket services
package sqlite3

sqlite3

Services to manipulate a Sqlite3 database
package template

template

Basic template system
package xdg_basedir

xdg_basedir

Services for using the XDG Base Directory specification

Parents

package app

app

app.nit, a framework for portable applications
package c

c

Structures and services for compatibility with the C language
package core

core

Nit common library of core classes and methods
package gamnit

gamnit

Portable game and multimedia framework for Nit
package java

java

Supporting services for the FFI with Java and to access Java libraries
package json

json

read and write JSON formatted text
package mnit

mnit

Children

package app

app

app.nit, a framework for portable applications
package egl

egl

Interface between rendering APIs (OpenGL, OpenGL ES, etc.) and the native windowing system.
package gamnit

gamnit

Portable game and multimedia framework for Nit
package glesv2

glesv2

OpenGL graphics rendering library for embedded systems, version 2.0

Descendants

package ios

ios

iOS support for app.nit
package linux

linux

Implementation of app.nit for the Linux platform