Qt для Android: настройка окружения и первая сборка APK

Qt позволяет писать кросс-платформенные мобильные приложения на C++/QML с единой базой кода для Android и iOS. В этой статье рассмотрим настройку окружения для сборки под Android и создадим минимальное приложение, которое компилируется в APK.

Что потребуется

Qt for Android — устанавливается через Qt Maintenance Tool или Qt Online Installer (выбрать компонент «Android» нужной версии Qt, например Qt 6.5 Android).
Android SDK — Command-line tools, Platform-tools, и хотя бы одна платформа (например android-33).
Android NDK — конкретная версия, совместимая с используемой версией Qt (актуальные требования указаны в документации Qt).
JDK (обычно OpenJDK 11 или 17, в зависимости от версии Gradle/Android Gradle Plugin).
Qt Creator (опционально, но удобно для настройки Kit’ов и отладки на устройстве).

Настройка Qt Creator для Android

В Qt Creator: Edit → Preferences → Devices → Android — указываем пути к SDK, NDK, JDK. Qt Creator автоматически предложит установить недостающие компоненты SDK (build-tools, platform-tools) при первом запуске.

После настройки в Edit → Preferences → Kits появится Kit вида «Android Qt 6.5.x Clang armeabi-v7a» — его нужно выбрать как активный Kit для проекта.

Минимальное приложение

Структура проекта:

MyAndroidApp/
├── CMakeLists.txt
├── main.cpp
└── main.qml

CMakeLists.txt:

cmake_minimum_required(VERSION 3.16)
project(MyAndroidApp VERSION 1.0 LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_AUTOMOC ON)

find_package(Qt6 REQUIRED COMPONENTS Core Gui Qml Quick)
qt_standard_project_setup(REQUIRES 6.5)

qt_add_executable(MyAndroidApp main.cpp)

qt_add_qml_module(MyAndroidApp
    URI MyAndroidApp
    VERSION 1.0
    QML_FILES main.qml
)

target_link_libraries(MyAndroidApp PRIVATE
    Qt6::Core Qt6::Gui Qt6::Qml Qt6::Quick
)

# Обязательные параметры для Android-сборки
set_target_properties(MyAndroidApp PROPERTIES
    QT_ANDROID_PACKAGE_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/android"
    QT_ANDROID_MIN_SDK_VERSION 24
    QT_ANDROID_TARGET_SDK_VERSION 33
)

main.cpp:

#include <QGuiApplication>
#include <QQmlApplicationEngine>

int main(int argc, char *argv[])
{
    QGuiApplication app(argc, argv);

    QQmlApplicationEngine engine;
    engine.loadFromModule("MyAndroidApp", "Main");

    if (engine.rootObjects().isEmpty())
        return -1;

    return app.exec();
}

main.qml:

import QtQuick
import QtQuick.Controls

ApplicationWindow {
    visible: true
    width: 480
    height: 800
    title: "Hello Android"

    Column {
        anchors.centerIn: parent
        spacing: 16

        Label {
            text: "Привет, Android!"
            font.pixelSize: 24
            anchors.horizontalCenter: parent.horizontalCenter
        }

        Button {
            text: "Нажми меня"
            anchors.horizontalCenter: parent.horizontalCenter
            onClicked: console.log("Кнопка нажата на устройстве")
        }
    }
}

Пояснения к коду

qt_add_qml_module регистрирует QML-модуль с указанным URI — это нужная для современного Qt6 (с qt_add_executable / CMake-интеграцией) практика, заменяющая ручное прописывание .qrc для QML-файлов.
QT_ANDROID_MIN_SDK_VERSION и QT_ANDROID_TARGET_SDK_VERSION задают совместимость с версиями Android API — без них сборка по умолчанию использует минимальные значения, которые Google Play может отклонить.
QT_ANDROID_PACKAGE_SOURCE_DIR указывает на директорию с дополнительными ресурсами Android (AndroidManifest.xml, иконки), если стандартного шаблона недостаточно.

Сборка APK

Из Qt Creator: выбираем Android Kit, нажимаем «Run» — Qt Creator сам соберёт .so-библиотеки через NDK, упакует их в APK через Gradle и установит на подключённое устройство/эмулятор.

Из командной строки (после настройки qt-cmake для Android-тулчейна):

qt-cmake -S . -B build-android -DCMAKE_BUILD_TYPE=Release
cmake --build build-android
cmake --build build-android --target apk

Готовый APK обычно появляется в build-android/android-build/build/outputs/apk/.

Подводные камни

Архитектуры процессора. По умолчанию может собираться только под одну ABI (например arm64-v8a). Для публикации в Google Play обычно нужно собрать под несколько архитектур (armeabi-v7a, arm64-v8a, x86_64) и упаковать в один App Bundle.
Разрешения (permissions). Доступ к камере, геолокации и интернету нужно прописывать в AndroidManifest.xml — Qt сам добавляет только базовые разрешения.
Размер APK. Qt-библиотеки заметно увеличивают размер приложения; для уменьшения размера используйте androiddeployqt с опцией минимизации, а также подключайте только нужные модули Qt.
Подпись приложения. Для публикации в Google Play APK должен быть подписан release-ключом — debug-сборка из Qt Creator для этого не подходит.
Совместимость NDK и версии Qt часто становится источником странных ошибок линковки — всегда проверяйте таблицу совместимости в документации конкретной версии Qt перед обновлением NDK.

Совет

Перед добавлением сложной логики протестируйте «пустое» приложение на реальном устройстве — это сразу выявит проблемы с настройкой SDK/NDK/JDK, прежде чем они смешаются с ошибками в собственном коде.

================================================================================