Android Build Reference

Technical reference for the OctoMY Android build infrastructure. OctoMY targets Android using the Qbs build system with Qt6.

Build Architecture

Qbs builds Android applications using its own packaging pipeline, without Gradle. The Android.sdk module handles:

1. Resource compilation via AAPT2
2. DEX compilation via d8
3. APK/AAB assembly directly

This differs from CMake-based Qt6 projects, which use Gradle as an intermediary.

Android Version Targeting

These values ensure compatibility with devices running Android 9 through Android 16, while meeting Google Play Store publishing requirements.

Project Structure

Each of the three applications has an android/ directory:

src/{agent,hub,remote}/android/
├── AndroidManifest.xml          # App manifest (package, permissions, activity)
└── res/
    ├── drawable-hdpi/icon.png   # App icon (high density)
    ├── drawable-mdpi/icon.png   # App icon (medium density)
    ├── drawable-ldpi/icon.png   # App icon (low density)
    └── values/libs.xml          # App name string resource

The signing keystore is stored separately at integration/cicd/targets/android-arm64/certificates/android_release.keystore.

AndroidManifest.xml

Each app's manifest declares the Qt6 Activity and application bindings:

<application android:name="org.qtproject.qt.android.bindings.QtApplication" ...>
    <activity android:name="org.qtproject.qt.android.bindings.QtActivity"
              android:exported="true" ...>
        <meta-data android:name="android.app.lib_name" android:value="{appname}"/>
    </activity>
    <provider android:name="androidx.core.content.FileProvider" .../>
</application>

Key elements:

Per-app differences:

Qbs Configuration

AndroidOptions.qbs

Located at integration/qbs/imports/AndroidOptions.qbs, this Properties block configures the Android SDK when targeting Android:

App.qbs Android Integration

App.qbs conditionally includes Android support:

• Dependencies: Android.sdk and Android.ndk (when targeting Android)
• Manifest: Points Android.sdk.manifestFile to the per-app AndroidManifest.xml
• Linker: Skips --start-group/--end-group flags (Android's lld resolves all archive symbols by default)

project.qbs

BuildOptions.qbs Android Guards

The following desktop-only features are disabled on Android:

• -fstack-clash-protection (not supported by NDK)
• -fuse-ld=mold / -fuse-ld=lld (NDK provides its own linker)
• cpp.cxxStandardLibrary (NDK always uses libc++)

QtDepends.qbs Module Exclusions

These Qt modules are excluded on Android builds:

Signing

The release keystore is at integration/cicd/targets/android-arm64/certificates/android_release.keystore. For release builds, configure signing via Qbs Android.sdk properties or environment variables.

ABI Support

OctoMY ships for arm64 (arm64-v8a) only on Android. This is a deliberate, permanent decision — armv7 / armeabi-v7a / any 32-bit ARM target is not supported and will not be re-added. The justification (no 32-bit Android hardware in the target market, Google Play 64-bit policy since 2019, libnative's JIT being fundamentally 64-bit by design) is in the root AGENTS.md under "Android architecture support" — read that before requesting armv7 support.

Supported profile

Build (example for Hub, debug APK):

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

The helper script integration/cicd/targets/android-arm64/build-android.sh wraps these commands and adds adb install/adb shell monkey steps. See the Build for Android howto.

AAB (Google Play) bundle

For Play Store distribution, build the release variant:

qbs build profile:android-arm64 qbs.buildVariant:release project.androidPackageType:aab -p hub

arm64-v8a alone covers the vast majority of active Play Store devices.

SDK/NDK Requirements

See also

• Build for Android — Step-by-step build instructions
• Qbs Build System — Build system architecture
• Platform Support — Cross-platform overview