Заметки по платформе и компилятору — Android

Эта страница содержит информацию, специфичную для создания приложений Qt и их запуска на платформе Android. Qt поддерживает версии Android 4.1 (уровень API 16) и более поздние.

Разработка для Android в Qt Creator

Самый простой способ разработки приложений Qt для Android — использование Qt Creator. При применении набора инструментов «Qt для Android» к проекту Qt Creator создаётся и поддерживается набор файлов, необходимых для работы приложения на Android.

В ваш проект добавляются следующие файлы:

• Файлы .java служат точкой входа в приложение и автоматически загружают Qt для выполнения нативного кода приложения
• AndroidManifest.xml, предоставляющий метаданные о вашем приложении
• Другие XML-файлы, описывающие зависимости приложения
• Файлы ресурсов
• В зависимости от выбранного метода развертывания в Qt Creator, в проект могут быть включены дополнительные файлы, такие как библиотеки и QML-файлы.

Qt Creator добавляет эти файлы в подкаталог вашего проекта, называемый android. Содержимое папки android используется в качестве основы для пакета распространяемого приложения.

Пакет приложения

На Android приложения распространяются на устройствах в пакетах, называемых APK.

Для распространения приложений в Google Play используется другой формат — AAB.

Хотя Qt Creator поддерживает построение обоих форматов пакетов, вы также можете создавать их вручную при необходимости. Для этого убедитесь, что необходимые пакеты и файлы сборки находятся на месте. Более подробную информацию о том, как выполняется упаковка, см. в Развертывании приложения на Android.

Особенности плагинов и импортов

Если приложение использует плагины, зависящие от других модулей, эти модули должны быть перечислены в зависимостях приложения. Это связано с тем, что Qt Creator не знает заранее, какие плагины ваше приложение загрузит в конечном итоге.

Например, если плагин зависит от Qt Multimedia, то модуль Qt Multimedia должен быть явно указан в качестве зависимости приложения, иначе плагин не может быть загружен. Вы можете сделать это, добавив его в файл .pro приложения:

QT += multimedia

Автоматический инструмент развертывания обнаруживает любые зависимости от QML-модулей, которые импортируются из кода приложения, но в особых случаях (например, когда QML-код генерируется кодом C++), это невозможно. Если этот сгенерированный код импортирует какие-либо специальные QML-модули, инструмент развертывания их не обнаружит и, следовательно, не включит в пакет приложения.

В этих случаях необходимо добавить «фиктивный» QML-код, импортирующий те же модули, что и сгенерированный код, чтобы автоматизированный инструмент обнаружил зависимости.

Особенности текста

Из-за ошибки в некоторых драйверах OpenGL механизм, используемый Qt для кэширования глифов текста, не работает должным образом на всех устройствах Android, что приводит к искажению текста. Для решения этой проблемы существует обходной путь, который увеличивает потребление памяти и может повлиять на производительность рендеринга текста. До Qt 5.3.2 обходной путь был включён только для определённого набора устройств. Теперь он используется по умолчанию на всех устройствах.

Вы можете отключить обходной путь, установив переменную среды QT_ANDROID_DISABLE_GLYPH_CACHE_WORKAROUND в значение 1. Это следует делать только после проверки того, что текст отображается правильно на всех целевых устройствах.

Особенности OpenGL

Современные устройства часто поддерживают OpenGL ES 3.0 или 3.1 в дополнение к 2.0. Чтобы получить подходящий контекст OpenGL, установите требуемую версию с помощью QSurfaceFormat::setVersion(). Однако обратите внимание, что заголовочные файлы доступны только в последних уровнях API, например, чтобы включить gl31.h, необходимо указать уровень API 21. Также имейте в виду, что использование функций OpenGL ES 3.x приведёт к поломке приложения на более старых устройствах, которые поддерживают только 2.0.

Особенности мультимедиа

Модуль Qt Multimedia Widgets не поддерживается на Android, что означает, что отображение видео доступно только с использованием VideoOutput и Video QML-типов.

Система файлов ресурсов

Qt для Android предоставляет специальную виртуальную файловую систему, основанную на механизме assets в Android. Файлы, помещённые в папку assets в каталоге android, созданном Qt Creator, будут упакованы как часть пакета вашего приложения. К ним можно получить доступ в Qt, добавив префикс assets:/ к путям. Например, чтобы получить доступ к изображению logo.png в папке assets/images, можно использовать QPixmap("assets:/images/logo.png").

Если механизм ресурсов не требуется для вашего приложения, рекомендуемый способ распространения ресурсов с вашим приложением Qt — использование Системы ресурсов Qt, которая является кроссплатформенным механизмом для распространения ресурсов с приложением.

Поддерживаемые архитектуры

В настоящее время Qt для Android имеет двоичные файлы для armv7a, arm64-v8a, x86 и x86-64.

Если вы хотите поддержать несколько различных ABI в своём приложении, рекомендуется создать пакет приложения (AAB), содержащий двоичные файлы для каждой ABI. На основании этого Google Play создаёт оптимизированные пакеты приложений (APK) для устройства, запрашивающего загрузку.

Пакет приложения (AAB) генерируется Qt Creator, если соответствующая опция выбрана в настройках проекта. Он также может быть создан из командной строки с помощью целевого файла «aab» в Makefile.

% make aab

Известные проблемы

Из-за ошибки на некоторых устройствах, когда вы отключаете предсказательный ввод с помощью ImhNoPredictiveText, это свойство будет проигнорировано, и предсказательный ввод всё равно будет включён. Для решения этой проблемы установите переменную среды QT_ANDROID_ENABLE_WORKAROUND_TO_DISABLE_PREDICTIVE_TEXT в значение 1. Однако побочным эффектом является то, что эта переменная среды может вызвать проблему с другими клавиатурами, такими как Gboard. Если вы используете язык, такой как японский, с Gboard, будет отображаться только клавиатура QWERTY. Эта переменная среды запрашивается каждый раз при отображении клавиатуры, поэтому можно переключать обходной путь включения/выключения по мере необходимости.

Поддерживаемые переменные среды

Для создания приложений с Qt для Android доступны следующие переменные среды.