Build a Feathers UI project as an Android app

Feathers UI may be used to build mobile applications targeting Google's Android operating system.

Prerequisites

In addition to the dependencies specified in the Feathers UI installation instructions, building an Android application with Feathers UI has some additional requirements.

  • Install the Java OpenJDK (version 11 or newer)

  • Download Android Studio

    • Launch Android Studio at least once to go through its setup wizard that downloads the Android SDK components.

  • Download Android NDK r21e (21.4.7075529)

    • Note: The Android NDK is not the same as the Android SDK. You need both.

    • You must download NDK version 21 at this time. NDK 22 and newer are not currently compatible with Haxe.

    • In Android Studio's SDK Manager, you can find the NDK in the SDK Tools tab. It will try to download the newest version by default. To see older versions of the NDK, you may need to select Show Package Details.

Configure OpenFL for Android

To set the locations of various tools required to build Android apps, you need to run the following command:

openfl setup android

It will request the paths to several of the required tools that were installed in previous steps.

Android SDK

Pass in the absolute path of the Android SDK.

Run Android Studio at least one time to go through its setup wizard that downloads the Android SDK components.

Typically, when the Android SDK is installed by Android Studio, it is located at a standard location on each platform:

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

Android NDK

Pass in the absolute path to the Android NDK.

Typically, Android Studio installs the NDK inside the SDK. The default path should be similar to below for each platform:

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

Java JDK

The Java JDK may be installed in a variety of locations, depending on which operating system you are using:

  • Windows: Typically, Java is installed to C:\Program Files\Temurin or C:\Program Files\Java
  • macOS: Run the /usr/libexec/java_home command in the Terminal app to find the JDK location.
  • Linux: Run the whereis java command in a terminal to find the JDK location. JAVA_HOME should be set to parent of the bin folder that contains the java executable.

Build

To build for the android target, run the following command.

openfl build android

Use the -debug flag to create a build to include extra debugging information, including full stack traces when there's an exception or crash.

openfl build android -debug

The build's output will be written to the bin/android/bin folder. The .apk file may be found in bin/android/bin/app/build/outputs/apk/debug (including release builds).

Your project.xml file may optionally specify an output folder different from bin.

<app path="Export"/>

In the example above, the output would be generated in Export/android/bin instead.

Run / Debug

OpenFL provides the test command to compile and launch your project executable on an Android device connected to your computer with USB.

openfl test android

Troubleshooting

Error on macOS says executables from the Android NDK "cannot be opened because the developer cannot be verified"

You may have downloaded the .zip version of the NDK, instead of the Mac App Bundle version of the NDK. The Mac App Bundle version of the NDK is signed and notarized, which means that macOS Gatekeeper trusts this version more, and you won't see these errors.

If, for some reason, you must use the .zip bundle, you can manually allow the executables through macOS Gatekeeper. However, be warned that it's a tedious process to get everything working correctly.

  1. In the "developer cannot be verified" error dialog, click Cancel and stop the current build in your terminal.

  2. Open the System Preferences app.

  3. Choose Security & Privacy.

  4. Go to the General tab.

  5. In the Allow apps downloaded from: section, click the Allow Anyway button.

  6. Start the build again.

  7. This time the pop-up will ask if you are sure that you want to open the executable. Click Open.

You may need to repeat this process many times, so keep the System Preferences app open so that you can click the Allow Anyway button when it appears again. The same executable name may fail more than once. This is normal. Android supports many CPU architectures, and each has its own set of executables.

Error: arm-linux-androideabi-g++: command not found

There is more than one possible reason for seeing this error:

  1. You may have downloaded the wrong version of the Android NDK. You must not use NDK versions newer than NDK r21 (and you probably shouldn't use versions older than r15c).

  2. You may have used the wrong path to the Android NDK on your file system. Check that the root folder of the SDK contains multiple sub-folders and files, including a README file.

Error: Failed to install the following Android SDK packages as some licences have not been accepted.

You may need to install a specific version of the Android SDK platform tools in Android Studio. The error message will include the version that you need, in a format like this:

platforms;android-28 Android SDK Platform 28

Open the Android Studio settings, and install the Android SDK platform tools with the specified API version. For the example above, API version 28 refers to Android 9.0 (Pie).

App executable crashes without exception, and a try/catch around the line where it happens has no effect when targeting C++ for Android or iOS

Haxe's cpp target is stricter than other Haxe targets when you try to access a field or method on a null value. Instead of throwing an exception, a Haxe C++ app immediately crashes — with no way to recover, not even with try/catch. However, it is possible to enable a flag to force Haxe's C++ target to behave more like other targets. Add the following define to your OpenFL project.xml file, and then create a new build with the -clean command line option (or delete your output directory before building).

<haxedef name="HXCPP_CHECK_POINTER" />

Using HXCPP_CHECK_POINTER may add some overhead that could negatively affect performance. It may be a good idea to enable it temporarily for debugging purposes, fix the issue, and then disable it again.

Did you get some other error message that you don't understand?

Configuring OpenFL to build for native targets, like iOS or Android, can be a little tricky! Head over to either the Feathers UI community forum or the Feathers UI Discord. Explain which command you tried to run, be sure to mention that you are targeting android, and post the error message (and any additional relevant output). Ideally, we can help you figure out a solution, and then we'll also add it to this troubleshooting section, so that everyone can benefit.