/**************************************************************************** ** ** Copyright (C) 2016 The Qt Company Ltd. ** Contact: https://www.qt.io/licensing/ ** ** This file is part of the documentation of the Qt Toolkit. ** ** $QT_BEGIN_LICENSE:FDL$ ** Commercial License Usage ** Licensees holding valid commercial Qt licenses may use this file in ** accordance with the commercial license agreement provided with the ** Software or, alternatively, in accordance with the terms contained in ** a written agreement between you and The Qt Company. For licensing terms ** and conditions see https://www.qt.io/terms-conditions. For further ** information use the contact form at https://www.qt.io/contact-us. ** ** GNU Free Documentation License Usage ** Alternatively, this file may be used under the terms of the GNU Free ** Documentation License version 1.3 as published by the Free Software ** Foundation and appearing in the file included in the packaging of ** this file. Please review the following information to ensure ** the GNU Free Documentation License version 1.3 requirements ** will be met: https://www.gnu.org/licenses/fdl-1.3.html. ** $QT_END_LICENSE$ ** ****************************************************************************/ /*! \page android-platform-notes.html \title Platform and Compiler Notes - Android This page contains information particular to building Qt applications for and running them on the \l{Qt for Android}{Android} platform. Qt supports Android versions 4.1 (API level 16) or later. \tableofcontents \section1 Android Development in Qt Creator The easiest way to develop with Qt for Android is to use \l{https://doc.qt.io/qtcreator/creator-developing-android.html}{Qt Creator}. When you apply a \b{Qt for Android Kit} to a Qt Creator project, it will create and maintain a set of files which are required to make your application run on Android. The files added to your project are: \list \li \e .java files will serve as the entry point into your application and automatically load Qt to execute the native code in your application \li \e AndroidManifest.xml which provides meta-information about your application \li Other XML files detailing the dependencies of your application \li Resource files \li Depending on the deployment method selected in Qt Creator, additional files like libraries and QML files can be included in the project. \endlist Qt Creator adds these files in a subdirectory of your project called \b android. The contents of the \b android folder is used as basis for your app's distributable application package. \section1 Application Package On Android, apps are distributed to devices in packages called \e APK. For distributing apps in Google Play, a different format called AAB is used instead. Although Qt Creator supports building both these package formats for you, you could also build them manually when needed. To do so, ensure that the necessary packages and build files are in place. For more detailed information about how the packaging is done, see \l{Deploying an Application on Android}. \section1 Plugins and Imports Special Considerations If an application uses plugins that depend on other modules, these modules must be listed in the application's dependencies. This is because Qt Creator does not know ahead of time which plugins your application will end up loading. For example, if a plugin depends on \l{Qt Multimedia}, then the Qt Multimedia module must explicitly be made a dependency of the application, otherwise the plugin cannot be loaded. You can do this by adding it to the application's \c .pro file: \code QT += multimedia \endcode The automatic deployment tool detects any dependencies on QML modules that are imported from the application's code, but in special case (for instance when QML code is generated by the C++ code), this is not possible. If this generated code imports any special QML modules, they are not detected by the deployment tool and therefore will not be included in the application bundle. In these cases, you must add "dummy" QML code importing the same modules as the generated code, so that the automated tool detects the dependencies. \section1 Text Special Considerations Because of a bug in some OpenGL drivers, the mechanism used by Qt to cache text glyphs does not work as expected on all Android devices, causing text to appear scrambled. To remedy this, a workaround is in place, which increases memory consumption and can also affect text rendering performance. Before Qt 5.3.2, the workaround was enabled only for a particular set of devices. It is now used by default on all devices. You can disable the workaround by setting the \c QT_ANDROID_DISABLE_GLYPH_CACHE_WORKAROUND environment variable to \c 1. You should do so only after verifying that text appears correctly on all targeted devices. \section1 OpenGL Special Considerations Modern devices often support OpenGL ES 3.0 or 3.1 in addition to 2.0. To get a suitable OpenGL context, set the requested version via QSurfaceFormat::setVersion(). Note however that the header files are only available in recent API levels, for example to include gl31.h, you need to target API level 21. Keep in mind also that using OpenGL ES 3.x features will result in the application breaking on older devices that only support 2.0. \section1 Multimedia Special Considerations The \l{Qt Multimedia Widgets} module is not supported on Android, which means video display is only available using the VideoOutput and the \l [QML]{QtMultimedia::}{Video} QML Type. \section1 Assets File System Qt for Android provides a special, virtual file system which is based on the \e assets mechanism in Android. Files that are put under \e assets in the \e android folder created by Qt Creator, will be packaged as part of your application package. These can be accessed in Qt by prefixing the paths with \c{assets:/}. For instance, to access the image \e logo.png in the folder \e{assets/images}, you can use \c QPixmap("assets:/images/logo.png"). If using the assets mechanism is not required for your app, the recommended way of distributing resources with your Qt app is to use \l{The Qt Resource System}, which is a cross-platform mechanism for distributing resources with your app. \section1 Supported Architectures Qt for Android currently has binaries for armv7a, arm64-v8a, x86 and x86-64. If you want to support several different ABIs in your application, the recommendation is to build an Application App Bundle (AAB) containing binaries for each of the ABIs. Based on this, Google Play generates optimized Application Packages (APK) for the device issuing the download request. The Application App Bundle is generated by Qt Creator, if the corresponding checkbox for this is selected in the project settings. It can also be built from the command line by using the "aab" Makefile target. \code % make aab \endcode \section1 Known Issues Due to a bug on some devices, when you turn off predictive text with \c ImhNoPredictiveText, this property will be ignored and predictive text will still be enabled. To work around this, set the \c QT_ANDROID_ENABLE_WORKAROUND_TO_DISABLE_PREDICTIVE_TEXT environment variable to \c 1. However, one side effect is that this environment variable can cause a problem with other keyboards such as Gboard. If you use a language like Japanese, with Gboard, only a QWERTY keyboard is displayed. This environment variable is queried each time the keyboard is displayed, so it's possible to toggle the workaround on and off, as necessary. \section1 Supported Environment Variables The following environment variables are available for building applications with Qt for Android. \table \header \li Variable \li Description \row \li ANDROID_NDK_ROOT \li Specifies where the Android NDK is located. \row \li ANDROID_SDK_ROOT \li Specifies where the Android SDK is located. \row \li ANDROID_NDK_PLATFORM \li Specifies the NDK API version; the default is android-21. \row \li ANDROID_API_VERSION \li Specifies the Java API version, which can differ from your NDK API version (ANDROID_NDK_PLATFORM). The default is the highest API version found on your system. \row \li ANDROID_NDK_HOST \li Specifies the host for which the toolchain was built. For example, \c{linux-x86_64} for Linux, \c{windows{} for Windows, and \c{darwin-x86_64} for macOS. \note This variable is detected automatically. Normally, you don't have to change it. \row \li ANDROID_BUILD_TOOLS_REVISION \li Specifies the version of the SDK build tools used as part of the deployment process. For example, 28.0.3. \note Currently in the \c{build.gradle} script file, a known working value is hardcoded; so you don't have to change it. \endtable */