Qt on Android Episode 3

Update: Here you can read also the Chinese version, thanks goes to Foruok.

Use Qt on Android

After we learned how to setup the development environment, we'll move forward in this article and learn how to use Qt Creator 3.0 (the one that comes with Qt 5.2 SDK) to create, run, debug and setup Qt apps on Android. The article covers only the Android specific Qt Creator parts!

Prepare your Qt Project for Android

If you want to start a new project or just want to test if you've setup the development environment correctly, then when you create a new project make sure you are also choosing an Android KIT. Check the following image:

If you already have a project and you want to Androidize it, you just need to add an Android KIT to your existing project. Check the following image:

To compile, deploy, run and debug Android apps, first you need to select an Android KIT. Check the following image:

Let's test it !

To test the application on Android just press the Run/Debug button!
Shortly a dialog will appear listing all compatible/incompatible connected devices and available emulators. Choose the desired device, and if you are planning to use the same device to run more than once this application, then you should check Use this device for architecture.., which means that you'll will not be bothered again, Qt Creator will use this device automatically. The following image shows you how it looks on my computer:

If there is no device listed there then you should check first if you've setup the development environment correctly.

In a few moments your application should run on your device. If you choose an AVD, it will take some time until it starts, so, please be patient!

If you checked Use this device for architecture ..., this option is remembered by Qt Creator until you reset the default devices or you close the project session. To reset the default devices, you need to open Projects perspective, click on Run tab, expand Deploy configurations and click on Reset Default Devices button.

You don't need to do anything special to debug Qt apps on your device/emulator, it just works out of box. Just make sure that your device uses Android API-10+.

Android Manifest

Every single Android application needs a manifest file. This is the entry point of your application, Android uses this file to decide which Application/Activity to start, it contains the application permissions, declares the minimum and the target Android API that application needs, and many more things.
androiddeployqt (a tool used by Qt Creator to deploy your application) uses an Android Manifest template and fills a few default values to run your application. But in order to publish your application it is not enough, so we need to create an AndroidManifest.xml file. To do that, open Projects perspective, click on Run tab, expand Deploy configurations and click on Create AndroidmManifest.xml button. Don't forget to add this file to your SCM. Check the following image too see how you create an AndroidManifest.xml file:

Now, after we've created the AndroidmManifest.xml it's time to set it up. Qt Creator should open the AndroidmManifest.xml file automatically after you created it.

As you can see Qt Creator provides a nice, easy to use editor for it. Using the editor you can set the following fields:

• Package name. The package name is:
  • reversed URL e.g. com.kdab.QtControlsExample
  • serves as a unique identifier
  • don't change after publishing, app would no longer be upgradable
• Version code/name. Next step is to set the version code and version name. For the start you don't need to change anything, but every time when you publish a new application you must change these fields, so they are very important.
  • Version code - used by Android and markets to distinguish between versions
  • Version name - user visible version string, displayed by Android O.S. and markets
  • Change (increase) both for every new release

  For more information about application versions check: http://developer.android.com/tools/publishing/versioning.html

• Minimum and target SDK. Qt Creator editor uses Minimum and Target SDK to set node attributes.
  • Minimum required SDK - edits android:minSdkVersion attribute. Is an integer API version that is used by Android markets to filter the devices that can install the application. It also used by Android O.S. to prevent the application to be installed on lower versions.
  • Target SDK - edits android:targetSdkVersion attribute.
    Android docs says:"This attribute informs the system that you have tested against the target version and the system should not enable any compatibility behaviors to maintain your app's forward-compatibility with the target version. The application is still able to run on older versions (down to minSdkVersion)."
    This attribute should not have any effects for Qt only Android apps though.

  For more information about application SDK versions check: http://developer.android.com/guide/topics/manifest/uses-sdk-element.html

• Application name. Qt Creator helps you only to set the application name only for English version.
• Run. Here you should select the application that you want to start. Most of the projects have only one application, so, it is not necessary to select anything here.
• Permissions. Permissions are very important for an Android application. If you don't set them properly your application can't access O.S. resources (e.g. network, write on external storage, etc.).
  Starting with Qt 5.2 SDK, qmake uses ANDROID_PERMISSIONS variable to set the minimum permissions for every Qt Module that should be set automatically by androiddeployqt tool, but in some cases you need to add/remove them manually. Qt Creator helps you on this matter with a nice permissions editor.
  Your application should not declare more permissions than it really needs because it will scare away the users!
  Please consult Android's manifest permissions page for more informations on this topic: http://developer.android.com/reference/android/Manifest.permission.html

This is how the Qt Creator Android manifest editor looks like for my QtQuick example application. My example application doesn't need any special permissions, so I removed all of them.

The Android manifest is quite complicated sometime you need to edit it manually. Qt Creator allows you to switch to XML Source.

The Android manifest is a beast! To master it please start by reading Android's manifest page: http://developer.android.com/guide/topics/manifest/manifest-intro.html

Android Target SDK, this is the SDK used to compile the java part of your application.
Don't be afraid to select the highest SDK available, your application will still run on any Android API-9+. Qt's java part is using only API-9 code!

"Say what? Yet another SDK? How many SDK do we need to set?" Well there are 4 (four) Android SDKs involved :), in the manifest file are 3 (Minimum, Target and Maximum) and this one.

Additional libraries. Use this editor to add any 3rd party libs to your project. Qt Creator edits your .pro file and it sets ANDROID_EXTRA_LIBS qmake variable. Of course the developer should not try to mix incompatible libs e.g. a x86 library can't be used by an arm application.

Because KDAB guidelines says that I should not create articles which have more than 1k words (and this one has more) I need to stop here. See you next time when we'll see what deploying systems are available for Qt on Android and how we do the package signing. These two steps are the most important before publishing!