Qt Weekly #3: Qt for Android - Tips and Tricks

The Qt installation packages contain Qt for Android libraries and useful tools for developing Qt apps for Android devices. However, you will need to install the Android NDK and SDK, and some other tools yourself and configure them for use with Qt Creator.

In this blog post, we'll walk-through the Qt for Android development process, from the environment set up to the deployment to the store. These details are also available in the official product documentation: Qt documentation.

Besides the developement process, we will also discuss a few platform-specific findings that might be useful.

Setting Up the Environment

The getting started documentation gives you the setup instructions. Where to get the Android SDK, NDK, Apache Ant and JDK (or openJDK), and on Windows the additional minGW and Android Debug Bridge driver links.

Note: From Qt 5.3.0, the offline installer for Windows will also include minGW., so you won't have to install it separately if you select it during the installation.

The following are a few platform-specific issues that must be handled for better development experience.

Linux 64-bit: Android SDK installation on 64-bit Linux machines (Ubuntu, Fedora) often doesn't work out of the box. Running <PATH_SDK>/platform-tools/adb can return errors like:

• Ubuntu: bash: ./adb: No such file or directory
• Fedora: adb: /lib/ld-linux.so.2: bad ELF interpreter: No such file or directory or adb: error while loading shared libraries: libstdc++.so.6: cannot open shared object file: No such file or directory

This is because the SDK comes with 32-bit version of the libraries. To fix this problem you can install:

• Ubuntu: sudo apt-get install libstdc++6:i386
• Fedora: yum install glibc.i686 glibc-devel.i686 libstdc++.i686 zlib-devel.i686 ncurses-devel.i686 libX11-devel.i686 libXrender.i686 libXrandr.i686

Windows: Consider installing the Android NDK in a "short" path. Otherwise, you may experience the following errors (or similar):

"mingw32-make: *** No rule to make target '..\..\..\..\..\..\..\android\android-ndk-r9b-windows-x86_64\android-ndk-r9b\sources\cxx-stl\gnu-libstdc++\4.8\include\profile\impl\profiler_map_to_unordered_map.h', needed by 'main.obj'.  Stop.The process "C:\Qt\Tools\mingw48_32\bin\mingw32-make.exe" exited with code 2."

Due to a platform limitation, this issue can arise when the path is too long (QTBUG-37113). Try installing the NDK directly in the root with a short directory name, and have a shallow directory structure for the project you are building. If you still have problems, try turning off shadow building, as this appends a long directory name to your path.

Note: If your application is using OpenSSL, have look at OpenSSL support page.

Deploying to the Device

There are three aspects to consider when deploying an application to an Android device:

1. Is my device successfully connected?
2. What is required from the application side so the application deployed works as expected? (what to do if my application uses plugins, how do I use resources, and so on.)
3. Which tool can help deploy the application to a device?

Before trying to deploy to a device, you should first enable USB debugging on the device. Follow the steps as described in the Android documentation:

• On most devices running Android 3.2 or older, you can find the option under Settings > Applications > Development.
• On Android 4.0, it's in Settings > Developer options.

Note: On Android 4.2 and later, Developer options is hidden by default. To make it available, go to Settings > About phone and tap Build number seven times. Return to the previous screen to find Developer options.

On Windows, the default USB drivers must be replaced with the OEM USB Drivers. You can usually find them on the device manufacturers' website. After downloading the relevant driver, follow these steps to update the existing USB driver:

1. Open the "Computer Management" tool (Computer->Manage) and then navigate to System Tools ->Device Manager
2. Right-click on your device and select "Update Driver Software..." from the context menu
3. Follow the steps and use the driver you have downloaded

For the Nexus devices, you can install the driver using the Android manager (Android documentation).

• Run <PATH_SDK>\tools\android.bat
• In the "Extras" section select and install "Google USB Driver".

To make sure that your device is successfully connected to your computer (1), run the following command and check that the device is listed in the output:

$ <PATH_SDK>/platform-tools/adb devices

For the tooling part (3), deploying an application to an Android device or emulator is very easy using Qt Creator. The following YouTube video demonstrates how easy it is to deploy a Qt application to several platforms using Qt Creator:

http://www.youtube.com/watch?v=WFGRr0DV3oM

Preparing Your Application for Submission

Before you can upload your application to the store, you need to prepare it for submission.

Adding a Manifest File

The default AndroidManifest.xml generated by Qt is suitable for development testing, but cannot be used to submit the application to Google Play.

Create your own manifest by clicking on the Create AndroidManifest.xml button in Qt Creator. This is located under Projects, in the Run tab. Expand Deployment configurations to see it.

Once the manifest has been added to your project, you can modify it. Most importantly, set the application name and package name. The package name should be a unique identifier for your application. A convention is to use the syntax, com.mycompany.myappname, where the "com.mycompany" namespace is based on Internet domain ownership to avoid naming collisions with other applications.

Note: Package name cannot be changed after the application is distributed to users.

Other important parts of the manifest include the versionCode, which must be incremented every time you upload a new version of the application. Other properties will decide how your application package is presented in the store listing, such as the application name and version name.

For more information on the AndroidManifest.xml, see the Android documentation.

Signing the Application

When your application is ready and you want to upload it to a store, you need to sign the Release APK (Android Application Package) file with your own private key. Open the Deployment configurations and set up the signing information there. When you are done, select Release as the build configuration and deploy your project. Once the build is complete, you will find the APK file in the build directory of your project.

Regarding the signing certificate, Qt Creator allows you to create a new keystore if you don't have one.

Note: Make sure you save this certificate for future upgrades of your application. If you loose the key and/or password, you will not be able to submit updates to your application. If you cannot sign an updated version with the same keystore that was used initialy, the user will install the new version as a completely new application..

Publishing to the Store

The first step is to get a publisher account if you do not already have one. Go to the Google Play developer console, log in with the Google account of your choice, and follow the steps as directed.

When you have set up your account, you can click on Add new application in Google Play's developer console. Take a look at the Android documetation for more info.

Note: Once you have a signed release APK, you can also use it in other stores: Amazon Store, Ovi Store for Nokia X, Kindle Store, Samsung Store. Not all Android applications are compatible with these Android-based platforms, but most of them are. Also if your application is compatible, you usually only need some additional screenshots to submit your application to those stores.

Related information

1. Qt for Android known issues
2. Android deployment in Qt 5.2
3. Update your application

Qt Weekly is a new blog post series that aims to give your daily Qt usage a boost. Stay tuned for next week’s post!