Qt

Deploying Applications to Android Devices

When you select a Qt for Android Kit for a project, Qt Creator creates and maintains a set of files that are required to make your application run on Android devices.

Qt Creator adds the following files to your project:

  • Java files, which serve as the entry point into your application and that automatically load Qt and execute the native code in your application.
  • AndroidManifest.xml, which provides meta-information about your application.
  • Other XML files, which specify the dependencies of your application.
  • Resource files.
  • Libraries and QML files, which can be included in the project depending on the deployment method that you select.

Qt Creator adds the files to the project to a subdirectory called android. The contents of the android folder are used to create a distributable application package.

Qt Creator supports the following methods of deployment for Android applications:

  • As a stand-alone, distributable application package (APK).
  • As a minimal APK that contains a dependency to the Ministro tool. The Ministro tool downloads the necessary Qt libraries from a repository of your choice.
  • As an incomplete APK that is suitable for testing and debugging applications on a device connected to the development host. The APK relies on the device containing the Qt libraries in the correct location. Qt Creator copies the libraries to that location the first time you deploy the application.

The default option depends on whether you are developing with Qt 4 or Qt 5. The Necessitas SDK does not support bundling Qt libraries with applications, so you must use Ministro when developing with Qt 4.

Specifying Settings for Application Packages

On Android, applications are distributed in packages called APK. Qt Creator creates the APK for you. If you want to do this manually, you must first make sure that the appropriate packaging and build files are in place. Qt Creator places the files in the android subfolder of the project.

To configure Android packages, select Projects > Run > Package configurations. The Android system uses the information from the file to start application components.

"Package configuration"

Selecting API Level

In the Android target SDK field, you can select the API level to use for the Android target SDK.

For more information about Android API levels, see What is API Level?.

The minimum API level is android-4 for Necessitas and android-9 for Qt 5. Qt Creator does not allow you to select an API level that the Qt version specified for the kit does not support.

Note: The android-4 API level does not support multitouch. If your application needs multitouch, select a higher API level.

Selecting Qt Libraries

In the Libraries group, specify which Qt libraries the application uses. To automatically determine this, select Read Infomation from Application (Must Be Compiled). Alternatively, you can manually select the Qt libraries and the external libraries you think your application needs. Make sure to arrange the libraries so that depended libraries appear before the ones that depend on them.

These entries are used by the Ministro tool to determine which Qt libraries to download.

In addition, the Java Loader uses this list to determine which Qt Libraries and other prebundled libraries to load with your application.

Signing Android Packages

In the Sign Package group you can sign the Android package by using a private key from the keystore. To create new keys, select Create.

"Sign Package"

Editing Manifest Files

To specify information for the Android manifest file, open it in Qt Creator.

"Android Manifest Editor"

Select the XML Source tab to edit the file in XML format.

In the Package name field, enter a package name for the application. The application is launched by an automatically generated Java launcher that is packaged with the application into an Android package (.apk). For more information, see Android Application Fundamentals.

You can specify an internal version number for the package in the Version code field. It is used to determine whether one version of the application is more recent than another. In the Version name field, specify the version number that is shown to users.

In the Application group, you can give the application a name and select an icon for it. The three icon fields can contain different versions of the icon with low, medium, and high DPI values, from left to right.

In the Permissions field, you can specify the permissions that your application needs. Users are asked to grant the permissions when they install the application. Android OS then grants the application access to the appropriate data and features.

To add permissions, select Add and select permissions from the list.

Deploying Application Packages

To specify settings for deploying applications to Android devices, select Projects > Run > Deploy configurations > Details.

"Deploy configurations"

To copy Qt libraries and files to the project directory and to bundle them as part of the APK, select the Bundle Qt libraries in APK option. This is the default option when developing with Qt 5. It is not supported when developing with Qt 4.

Using Ministro to Install Qt Libraries

To minimize the size of your APK, you can package the application with an external dependency called Ministro. If a user downloads your application, and it is the first application on their device to depend on Ministro, they are asked to install Ministro before they can run your application.

Ministro serves as a central repository for Qt libraries. This enables several applications to share the libraries, which only need to be installed once. To use this deployment method, you must set up a repository for the libraries that you want to distribute. To specify the repository URL, edit the file android/res/values/libs.xml, which is created by Qt Creator.

To use Ministro to install the Qt libraries, select the Use Ministro service to install Qt option.

This is the default option when developing with Qt 4.

Deploying Qt Libraries for Debugging

To test your application on a device that is physically connected to the development host (or on an emulator), you can copy the Qt libraries into a temporary directory on your device and run the application against them.

An APK built in this way is not distributable, since it relies on the device containing the Qt libraries in the correct location. However, as the Qt libraries are only copied into the device once, this method provides a fast turn-around time, and is therefore convenient for testing the application during development.

Select Projects > Run > Deploy configurations > Details, and then select the Deploy local Qt libraries to temporary directory option to deploy Qt libraries to the /data/local/tmp/qt folder on the device and to run the application against them.

To deploy new Qt libraries to the device, select Clean Temporary Libraries Directory on Device. The next time you deploy the application, Qt libraries are copied to the device again.

Installing Ministro

The easiest way to install Ministro is to do it on the device via Google Play. When you run the application for the first time, a dialog pops up and guides you through the installation.

To use Qt Creator to install Ministro, you must first download the Ministro .apk from the Google Market or from the Ministro home page.

Then select Install Ministro from APK in Projects > Run > Deploy configurations > Details.

You can use this option also to install any Android package (.apk).

You can use this option to install applications on an Android Virtual Device (AVD).