Android deployment in Qt 5.2

This is a quick update on one of the features we have planned in Qt 5.2 for Android. In this release, our main focus has been on improving the "Getting Started"-experience, and polishing in general. For example, this has implied quite a few improvements to how Android is presented in Qt Creator 3.0, to make it easier the first time you sit down to write an Android application in Qt.

Example of an improvement in Qt Creator 3.0. You will now get a message if your SDK is not yet set up correctly for use with Android.

One of the main problems was that, when building for Android, Qt Creator would add a set of generated files to the source code of your project. Some of these files contained a mixture of user-modifiable information and generated information. In principle, it is wrong to add generated build files to all projects just because they were built for Android once. Typically, only files which actually contain modifications particular to the project should have to be checked in to the revision system.

Another issue we were facing was the fact that all the packaging and deployment logic was inside of Qt Creator, which meant it couldn't easily be used in combination with other build systems and it couldn't easily be automated.

A third issue was the interdependency between Qt and Qt Creator. The template for the generated files were in Qt, whereas the instantiation of the template was contained in Qt Creator. Having the template in Qt makes sense, because it primarily need to stay in sync with other parts of Qt, such as the platform plugin and the Java helper library. But this meant that changes in Qt would often require changes to Qt Creator. Due to this, we had to synchronize release schedules and deadlines in a way they had not been before, adding an extra strain on the release process.

For the user, this would entail less flexibility in choosing when to upgrade. A new Qt for Android version would typically require a new version of Qt Creator every time. Maybe not the largest inconvenience, but still something which generated a fair share of bug reports and inquiries.

To fix these issues in Qt 5.2, we extracted the packaging and deployment logic from Qt Creator and put it into a command-line tool instead. This is currently to be found in the qttools repository, and is called "androiddeployqt". In addition, the logic was updated to no longer require any Android build files in your project. Using Qt 5.2 and the command-line tool, you should be able to take any regular .pro file, run

qmake
make install INSTALL_ROOT=android-build/
androiddeployqt --output android-build/

...and you will get an APK which you can install and run on your device. Note that this of course requires your application to be written in a cross-platform way. If you have resources on the file system, for instance, these should be added to a QRC file, or they should be installed into the android-build/assets directory of your package.

The android-build/ directory in this example is now a clean build directory which can be reproduced by repeating the steps above. You can delete the directory to clean out old packages and old build files. By default, it will only contain the files from an application template in Qt, with some changes applied on top to adapt to information from the .pro file. This should be a good starting point for any application, as it will let you focus on your cross-platform code initially and quickly get up and testing on an actual device. At some point before you release your application to users, however, you will probably want to add custom files to your project. At the very least, you will want to add an AndroidManifest.xml to describe the permissions required by your application and other information needed by the market place where you later upload it. This can also easily be done with the deployment tool. Simply add a directory to your project where you want to put the Android specific files and then add a reference to this in your .pro file. This directory will then be merged with the template, overwriting duplicate files. That way you can easily tailor the package exactly as you want when you get to the point where it makes sense to focus on this. Check out the documentation for more information on this.

Qt Creator 3.0 will automatically use this tool for any project based on Qt 5.2 or newer, so you don't have to worry about using the command-line tool yourself unless you want to, but you still get the clean separation between build files and source files in Qt 5.2. In addition, Qt Creator has the same (and more) convenience as it did before, allowing you to create and edit your AndroidManifest.xml, write, build, run, debug and even sign your application without ever leaving the Qt Creator UI.

So if you're interested in this, please try it out, either by downloading pre-release versions of the SDK or by building it manually from source. We'd very much like to hear about issues with it as soon as possible so we can fix them in time for the Qt 5.2 release.