Setup Android

Create native Android mobile applications with Lime and OpenFL by compiling to C++.

Automatic Install

There is no automatic setup available for Android.

Manual Install

Warning! Haxe 4.3 with hxcpp 4.3.2 on Haxelib cannot build working Lime apps for Android. The app builds, but when run on a device, it results in an SDL error about __atomic_compare_exchange_4 on app startup.

There are two known workarounds:

  • Downgrade to Haxe 4.2 and hxcpp 4.2
  • Install a development build of hxcpp from GitHub to use Haxe 4.3

At the time that you are reading this, if there is a newer version of hxcpp than 4.3.2 on Haxelib, you should be able to use that newer version without any of the above workarounds.

Similar to standard Android native development, you will need the following installed:

  • Java JDK
  • Android SDK
  • Android NDK

Java JDK

JDK version 11 or newer is recommended.

A variety of vendors offer free Java OpenJDK builds that work well with Lime, OpenFL, and Android. If you’re not sure which one to choose, a good option is Temurin OpenJDK from Adoptium.net.

Android SDK and NDK

To install the Android SDK and NDK, using Android Studio is recommended. Android Studio contains an SDK Manager that allows you to install all of the SDK and NDK components that you need (including the ability to select specific versions, if necessary).

SDK Platforms

In the SDK Platforms tab in Android Studio’s SDK Manager, you should generally be able to install the newest API Level.

Note: See Meet Google Play’s target API level requirement for details about which API levels Google currently requires for new apps and for updates.

SDK Tools

In the SDK Tools tab in Android Studio’s SDK Manager, you will need to install a few items.

You should generally be able to install the newest Android SDK Build-Tools.

NDK (Side by side) version r21e (21.4.7075529) is currently recommended for Lime.

Warning: hxcpp 4.3.2 and older on Haxelib do not support newer NDKs than r21e. When the next update after hxcpp 4.3.2 is released, it should support newer NDKs (at least up to NDK version 25).

You should generally be able to install the newest Android SDK Platform-Tools.

Configuring Lime for Android development

After all of the Android SDK and NDK tools are installed, Lime must be configured with their file system paths. Open a command prompt or terminal, and run the following command:

lime setup android

If prompted to automatically download and install any components, type the letter n (for “no”) and press Enter. Then, the setup process will ask for the location of each component. When prompted, enter the path to where the Android SDK, NDK and any additional components are installed.

Typically, when the Android SDK is installed by Android Studio, it is located at a standard location on each platform (specify the appropriate username and version, as necessary):

  • Windows: C:\Users\username\AppData\Local\Android\Sdk
  • macOS: ~/Library/Android/sdk
  • Linux: ~/Android/Sdk

Android Studio installs the NDK inside the SDK. The default location for each platform should be similar to below (specify the appropriate username and version, as necessary):

  • Windows: C:\Users\username\AppData\Local\Android\Sdk\ndk\version
  • macOS: ~/Library/Android/sdk/ndk/version
  • Linux: ~/Android/Sdk/ndk/version

The Java JDK may be installed to a variety of locations, depending on the current operating system, and which JDK distribution was selected:

  • Windows: Typically, Java is installed somewhere in C:\Program Files, such as C:\Program Files\Java or C:\Program Files\Temurin.
  • macOS: Run the /usr/libexec/java_home command in the Terminal app to find the JDK location.
  • Linux: The location depends on your distribution and package manager.

Build & Run

To compile an Android application bundle, run lime build android. Add the -debug option to create a debug build. Add the -release option to create a release build.

To compile and launch an Android application with one command, run lime test android. The app will run on a device connected to your computer with USB.

Note: In some cases, you may need to install drivers on your computer for your Android device before you can deploy an app to it.

Note: The first time that you compile a project for C++, it will take a noticably long time. However, compiling the same project again should be significantly faster because parts of your code that have not changed do not need to be recompiled. To force all of code to be recompiled for C++, use the -clean option.

Code Signing

During development, Android builds will automatically use a self-signed certificate. To distribute an Android app, you must specify code signing options. These may be added to a <certificate/> element in your project.xml file. You may need to add the if="android" attribute, if your app targets any other platforms besides Android.

Specify the path and alias attributes for your certificate.

<certificate path="path/to/keystore.p12" alias="1" if="android"/>

Need to know which aliases are included in your certificate?

Open a terminal, and run the following command to list the keystore entries, including alias names:

keytool -list -v -keystore path/to/keystore.p12

If the keytool command is not available on the system path, you may be able to find it in a Java JDK.

You should not save a keystore password in your project.xml file because it is a serious security risk. It is technically allowed, though.

<!-- you should NOT specify the password like this -->
<certificate path="path/to/keystore.p12" alias="1" password="hunter2" if="android"/>

Instead, you have two options.

  1. Specify the password on the command line. Example: --certificate-password=hunter2

  2. Don’t specify the password, and wait for the build to request it automatically.

Advanced Configuration

The <config:android /> element in your project.xml file is used to specify advanced configuration options for Android. A few of the more commonly-used advanced configuration options for Android are documented below. For more details about the available advanced options, see Config Values: Android.

The <config:cpp /> element in your project.xml file is used to specify advanced configuration options for C++. For a complete list of these advanced option, see Config Values: C++.

Target and Minimum SDK Versions

If Lime’s default values for Android’s targetSdkVersion and minSdkVersion don’t meet your project’s needs, you can specify custom values in your project.xml file.

<config:android target-sdk-version="23"/>

<config:android minimum-sdk-version="14"/>

Android Build Tools Version

Gradle requires specific versions of the Android SDK Build-Tools, and Lime will try to find the latest version installed.

If Lime’s default values for Android’s build tools version doesn’t meet your project’s needs, you can specify a custom value in your project.xml file.

<config:android build-tools-version="35" />

Gradle Versions

If Lime’s default values for Gradle versions used to build for Android don’t meet your project’s needs, you can specify custom values in your project.xml file.

<config:android gradle-version="7.4.2" gradle-plugin="7.3.1" />

Permissions

If Lime’s default values for Android permissions don’t meet your project’s needs, you can specify custom values in your project.xml file.

<config:android permission="android.permission.ACCESS_FINE_LOCATION" />

Use multiple tags to specify more than one permission.

<config:android permission="android.permission.INTERNET" />
<config:android permission="android.permission.ACCESS_NETWORK_STATE" />

Android Emulator

If you intend to test with the Android emulator, you create an AVD in Android Studio in the Virtual Device Manager.

Add the -emulator option to your lime build android or lime test android command to target the Android emulator instead of a device.

Help & Forums

If you encounter any problems when setting up Lime for Android, please visit the forums or Discord.


Improve this page