Qt for Android
Qt for Android enables you to run Qt 5 applications on devices with Android v2.3.3 (API level 10) or later. All Qt modules (essential and add-on) are supported except Qt WebKit, Qt Bluetooth, Qt NFC, Qt Positioning, Qt Serial Port, and the platform-specific ones (Qt Mac Extras, Qt Windows Extras, and Qt X11 Extras).
The following list summarizes what you can do with Qt for Android:
- Run Widget and QML applications on the device or emulator.
- Handle Multimedia content in your Qt Quick 2 applications.
- Get sensor readings and react to the changes.
- Develop secure applications using OpenSSL library.
- Create and deploy Application Package (APK) using Qt Creator or the command-line tool, androiddeployqt.
Getting Started
Requirements
In order to use Qt for Android, you need the following:
- The Android SDK Tools
- The Android NDK
- Apache Ant v1.8 or later
- OpenJDK v6 or later
- On Windows, you need the following additional installations:
- MinGW v4.8.0
- Android Debug Bridge (ADB) driver on the Windows platform to enable USB debugging. The default USB driver on Windows does not allow debugging. You can download the ADB driver from the device manufacturer's support website. For example, the ADB driver for Google Nexus 7 can be downloaded from http://support.asus.com.
After installing the driver, try running a few basic adb commands and check whether your device responds to it.
Note: You must set the JAVA_HOME environment variable to the JDK install directory path so that Qt Creator finds the binaries required to build your application.
After installing these tools, update the Android SDK to get the API and tools packages required for development. You can update the SDK using the android tool that comes with the SDK Tools package. For example, on Ubuntu the following command starts the Android SDK Manager, which enables you to select the packages you want to install:
./android update sdk
Installing Qt for Android
You can install the binary package for Qt 5.1 or later to get Qt for Android. The installer containing the binary packages are available for download from the Qt project Downloads page.
You can also choose to build the binaries from the Qt sources, that is, cross-compile Qt 5.x for Android on Linux (X11) , Windows, and Mac OS X platforms. If you chose to do so, here is how you can do it:
- Install the required tools, SDK, and the compiler toolchains listed in the Requirements section.
Note: Ensure that your build environment fulfills the requirement for the platform (Linux, Mac OS X, and Windows) you have chosen.
- Set the following environment variables if your build platform is Windows:
- ANDROID_NDK_HOST=windows or windows-x86-64 depending on which NDK you are using.
- PATH=%JAVA_HOME%\bin;<MINGW_ROOT>\bin;%PATH%
- Download the Qt 5 sources either from the Downloads page or from the Git repository.
Note: If you are downloading the sources from the Git repository, you must initialize your Git clone using the perl init-repository command to pull the latest sources for all the Qt 5.x modules. Ensure that you have perl v5.14 or later installed.
- Run the following command to configure the Qt 5.x sources to cross-compile Qt for Android:
On Linux/X11 and Mac OS X:
./configure -developer-build -xplatform android-g++ -nomake tests -nomake examples -android-ndk <path/to/ndk> -android-sdk <path/to/sdk> -android-toolchain-version <e.g. 4.8> -skip qttranslations -skip qtwebkit -skip qtserialport -skip qtwebkit-examples
On Windows:
configure.bat -developer-build -platform win32-g++ -xplatform android-g++ -android-ndk <ANDROID_NDK_ROOT> -android-sdk <ANDROID_SDK> -opensource -confirm-license -nomake tests -nomake examples -skip qttranslations -skip qtwebkit -skip qtserialport -skip qtwebkit-examples
- Start the build by using the make or mingw32-make (on Windows) utility with the -j<N> switch (used to speedup building).
The binaries are installed to the qtbase/bin directory by default for the developer builds. You can check the install paths using the qmake -query command.
Configuring Qt Creator
After installing the Qt for Android binaries either using the installer or by cross-compiling, Qt Creator must be configured to start developing your first Qt application for Android.
Note: You must install Qt Creator separately (either using the stand-alone or Qt 5 installer provided by Qt project, or by building it from the source) if you built the Qt 5.x binaries from the sources. Use the 3.0 git branch if you are building it from the source.
See Qt Creator Manual for instructions to configure and test your setup by creating a simple Qt Quick application. You can also try running an example on the Android target to test the setup. Use the android keyword in the search field under the Examples tab in Qt Creator Welcome mode to list all the examples tested for Android.
Porting an Existing Qt Application
In this section, we are going to port an existing Qt Application to Android and deploy it to the device.
Most Qt applications should be portable to Android with ease, unless they depend on a specific hardware or software feature not supported by Android. If your application is not using any such feature, deployment is probably the only step that demands some changes to your application.
Like most UI applications, Qt applications also depend on resources such as images, icons, translation files, and so on. These resources must be made available on the device as they are required for the application to function effectively.
The most convenient option is to bundle the resources into a qrc file, which gets built into the application binary. This approach reduces the porting effort considerably and provides faster access to the resources. It is also a cross-platform approach, which makes porting to other platforms easier.
By default, all Qt applications can access the contents of a qrc file using the ":/" prefix or the URL scheme prefix, "qrc:". To know more about qrc files and how they are handled, see the Qt Resource System.
The other approach is to deploy the resources into the package's assets directory. It is the best option if you want to achieve better interoperability with the Android APIs. You can access all resources in the directory using the "assets:" prefix. Unlike qrc, this approach is not a cross-platform solution.
The following step-by-step instructions guide you to port an existing Qt Quick application to Android using the qrc approach:
- Open the existing project in Qt Creator and configure it with "Android for ARM" kit. For more information, see Qt Creator: Configuring Projects
- Update all local directory imports in the qml files to use a local namespace. For example, to import the QML documents in the "contents" directory relative to main.qml, use the following import statement:
import "contents" as Contents
- Identify all the resources used by your application and add them to one or more qrc files. Qt Creator updates your qmake project file with the "RESOURCES" variable listing the qrc files you added.
- To load or refer to the resources in the qrc file from a C++ file, use the "qrc:" prefix with the URL. For example, to load the main.qml file from resources.qrc, you can use the following code in your main function:
QQuickView viewer; viewer.setSource(QUrl("qrc:qml/main.qml")); viewer.show();
Note: QML documents can refer to the contents in qrc files using the relative path to the document. Such references do not require the "qrc:" or ":/" prefix.
- Update the "Run" settings for your project as described in the Qt Creator: Specifying Run Settings
Note: You can change the default settings for application icons and identifier.
- If your application uses imports or plugins which depend on special Qt modules, these Qt modules should be added to the .pro file. For example, if your application uses the Qt Multimedia import in QML, you should add the following to your .pro file:
QT += multimedia
- Save the changes to your project and run the application.
Qt Creator deploys your application on the Android device, if the device is detected by the PC. Otherwise, it tries to run the application on an AVD (Android Virtual Device). You will be prompted to create one if there are no AVDs found.