Build for Android

Compile and install OctoMY's three Android apps (Agent, Hub, Remote) onto a physical Android device. The only Android target this guide covers (and the only one OctoMY ships for) is arm64-v8a — modern 64-bit Android phones, Android 9+, which is every device shipped since around 2020 including budget and rugged industrial tiers. 32-bit ARM (armv7 / armeabi-v7a) is a deliberate, permanent non-target — see the Android architecture support note below.

There is no Gradle in this pipeline — Qbs handles APK/AAB assembly directly via its Android.sdk module.

Prerequisites

Install the following before building:

One-time profile setup

Create a Qbs profile for each ABI you want to target. Use qbs setup-android so the Android SDK/NDK module settings are filled in automatically; then attach the matching Qt Android install.

arm64-v8a (modern phones)

qbs setup-android \
    --sdk-dir ~/Android/Sdk \
    --ndk-dir ~/Android/Sdk/ndk/26.1.10909125 \
    --qt-dir ~/Qt/6.10.1/android_arm64_v8a \
    android-arm64

# JDK pointers used by the Android packaging steps
qbs config profiles.android-arm64.java.jdkPath /usr/lib/jvm/java-21-openjdk-amd64
qbs config profiles.android-arm64.java.compilerVersion 21.0.10

Android architecture support

OctoMY ships for arm64 (arm64-v8a) only. armv7 / armeabi-v7a / any 32-bit ARM target is a deliberate, permanent non-target — do not attempt to re-enable it. Reasons (no 32-bit Android hardware in the target market, Google Play 64-bit policy, libnative's JIT being fundamentally 64-bit by design) are documented in the project root AGENTS.md under "Android architecture support" — read that before opening an issue or filing a PR that touches this.

Verify the profile with:

qbs config --list profiles.android-arm64

Build and deploy

Use the helper script for the common case (build + install + launch):

# Syntax: build-android.sh <agent|hub|remote> <arm64> [build|install|build-install|run]
integration/cicd/targets/android-arm64/build-android.sh hub arm64 run
integration/cicd/targets/android-arm64/build-android.sh agent arm64 build

The script is a transparent wrapper around the raw qbs build and adb install commands shown below; it exists so you don't have to remember the argument list.

Raw build command

qbs build \
    -f project.qbs \
    -d .build/android-arm64-debug \
    profile:android-arm64 \
    qbs.buildVariant:debug \
    project.androidOpenSslInclude:$HOME/Android/Sdk/android_openssl/ssl_3/include \
    -p hub

Substitute the product (agent, hub, or remote). Only the android-arm64 profile is supported; see the architecture support note.

Install to a device

adb devices                           # make sure the device is visible
adb install -r .build/android-arm64-debug/default/hub.*/org.octomy.hub.apk
adb shell monkey -p org.octomy.hub -c android.intent.category.LAUNCHER 1

The APK path wildcard (hub.*) covers the hash-suffixed build directory that Qbs creates.

Release builds and signing

Release builds use the keystore at integration/cicd/targets/android-arm64/certificates/android_release.keystore. Switch qbs.buildVariant to release, and optionally set androidPackageType to aab for Google Play Store submission:

qbs build \
    -f project.qbs \
    -d .build/android-arm64-release \
    profile:android-arm64 \
    qbs.buildVariant:release \
    project.androidPackageType:aab \
    project.androidOpenSslInclude:$HOME/Android/Sdk/android_openssl/ssl_3/include \
    -p hub

Qbs invokes the signer automatically when Android.sdk.keystoreLocation is configured (see integration/qbs/imports/AndroidOptions.qbs).

Troubleshooting

INSTALL_FAILED_NO_MATCHING_ABIS

The APK is built for an ABI the device doesn't support. Check the device's supported ABIs:

adb shell getprop ro.product.cpu.abilist

Rebuild against android-arm64 (the only supported profile).

Dependency 'Qt.core' not found

The Qbs profile's Qt module provider is pointing at a Qt install that lacks the requested module, or the architecture doesn't match. Re-run qbs setup-android ... --qt-dir ... with the correct Qt Android install.

openssl/evp.h: No such file or directory

project.androidOpenSslInclude wasn't passed. Either set it on the command line (see examples above) or via OCTOMY_OPENSSL_INCLUDE if you use the helper script.

App crashes on launch

Capture a device log and filter for Qt / the app's package:

adb logcat -c && adb logcat '*:W' octomy:V libc:V DEBUG:V

Common causes: wrong android.app.lib_name in the manifest, missing Qt plugin (e.g. no OpenGL ES), or a real runtime assertion.

See also

• Android Build Reference — Technical configuration details
• Qbs Build System — Build system internals