Eskil Abrahamsen Blomfeldt

Android deployment in Qt 5.2

Published Wednesday October 9th, 2013
19 Comments on Android deployment in Qt 5.2
Posted in Android, Build system, Qt, QtCreator

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.

Screenshot of new kit selection feature in Qt Creator 3.0

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

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.

Do you like this? Share it
Share on LinkedInGoogle+Share on FacebookTweet about this on Twitter

Posted in Android, Build system, Qt, QtCreator


Lilian says:

Thank you guys for your efforts!
I think I’ll wait for the Beta to test…

Dasun says:

I’ll keep my fingers crossed for beta!

I’ve begun working on a “windeployqt” tool too.

You can see the beginnings here:;a=blob;f=subsurface-install.pri;hb=HEAD#l55;a=blob;f=scripts/;hb=HEAD

Do you think it would be useful to move to qttools?

Maurice Kalinowski Maurice Kalinowski says:

@Thiago, please check the qttools in stable where we are working on windeployqt, with slightly different approach, but working for Win, WinRT and WinPhone. You can also check with fkleint about details.

At least the first patch seems to be clearly a mingw only solution.

Steve says:

Sounds like a suitably clean separation… it wasn’t clear which files needed to be under version control in android projects for 5.1 and so I added them all. I’ll wait for the binary betas before giving it a go though.

m][sko says:

Is it possible to add some java code to generated files for some specific behavior ?

Eskil Abrahamsen Blomfeldt Eskil Abrahamsen Blomfeldt says:

The preferred way to add Java code is to add your own Java files and subclass the generated files to override its behavior.

If you want, it’s also possible to put a modified for instance in your Android package source, and this will then overwrite the generated This will however mean that you need to make sure it’s properly updated if you upgrade to a new Qt version.

Benoit says:

I tried one of the 5.2.0-beta1 snapshots, working great so far, I like the simplicity of the whole process, great, great work! The only thing I am missing is a QtWidgets-free version of QtQuickControls (which is probably the most common use case for Android deplyment) in order to reduce the package size. I can of course compile it myself but that would be useful for many users to have it in the binary package.

Eskil Abrahamsen Blomfeldt Eskil Abrahamsen Blomfeldt says:

I agree. We’ll look into removing the widgets-dependency by default in Qt 5.2.

Cyttorak says:

What about apk file sizes with all its Qt stuff bundled? Are they compeititive or still needs some wo rk?

Eskil Abrahamsen Blomfeldt Eskil Abrahamsen Blomfeldt says:

A default “Hello World” APK in Qt Quick 2 which includes the necessary Qt libraries, plugins and imports will be around 9 MB.

Cyttorak says:

Not too bad I guess 🙂

J says:

This is really great news. Good job, Qt team!

Thorsten Zachmann says:

Is there a possibility like in the old android support to only get the libaries needed into the package? Currently it seems to copy all in with a lot of stuff not needed

Eskil Abrahamsen Blomfeldt Eskil Abrahamsen Blomfeldt says:

Currently, the auto-detection will be greedy, including all relevant plugins and imports and their dependencies, since we don’t have any way to know currently which ones will be used at run-time. The overhead of this is pretty minimal compared to the overhead of the required libraries.

For QML imports, we’ll improve this to be smarter, thus only including the ones that are actually used. Work for this is in progress.

It’s also possible to completely override the auto-detection manually to specify precisely which libraries, plugins and files should be included. I’d expect this to be an appropriate extra step right before going into production with an app. See the documentation for details on this.

Suppaman says:


This “separation” mean it will be some possibility in the future to develop for android (compiling, packaging and deploy) using Visual Studio 2013 through plugin instead to use Qt Creator?

Thank you

Robert says:

This is a great improvement particularly in for working with several kits and several CPUs like ARM and Intel (coming at some new Samsung tablets).

Just to remind you that child window bugs related
to sizes and positioning of dialogs, etc. child windows are actually show-stoppers for porting QWidgets – based applications. There are about 10 such issues filed in JIRA whereas it could be that there are only 2-3 real issues behind these 10 reports.

Thank you in advance!

AndreasL says:

This is great news, I’ve been wanting a cleaner separation for some time. Good job!

Filip Piechocki says:

First of all I really like where Qt is heading now, Qt Quick 2 with opengl and scenegraph is pretty awesome, but… a lot of Qt features really look like a technology preview rather than final product. It is nice to have new features but it would be better to have existing features refined. Now it looks like KDE4 when it became usable with version 4.5+ but in the meantime I’ve switched to gnome…

Commenting closed.

Get started today with Qt Download now