Qt on Android Episode 3 - How to use Qt Creator to create, run, debug and setup Qt applications on Android
21.01.2014
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!
Has anybody run Qt 3D from git on Android? I haven’t tried it myself, and don’t want to try if it isn’t going to work
Personally I didn’t try it, but it should work …
I’d like to translate your post to Chinese, and post on http://www.csdn.net. My blog is http://blog.csdn.net/foruok. I had translate episode 1 today. Can you give me the authorization ?
Sure, no problem at all!
You can send me the links to these translations and I’ll add them for Chinese people that wants to read them in Chinese.
And I have a question, how can I implement a Android service use Qt on Android ?
Keep an eye on KDAB’s blogs, I’ll write an article about it 🙂 !
Hi, BogDan Vatra:
here is the Chinese version of Qt on Android Episode 1, http://blog.csdn.net/foruok/article/details/18697377。
Because I don’t have your email, I’ll post the link below your posts. Here is my email: foruok@163.com, if necessary, please contact me.
Hello, BogDan Vatra, I love ur blogs. Could you help me with one quesition about qt for android ,please? How to add .so file into apk?,I found ‘Additional libraries’ editor is always disabled ,how can I enable that ? Looking forward to ur reply, thank you very much. And hope to see more blogs！
Additional libraries *should* be enabled …
Anyway, if for some is disabled, the you can manually edit your .pro file and add the full path to your lib to “ANDROID_EXTRA_LIBS” qmake variable.
Thanks for shares.I ‘m new at Qt world and I finished a game using qml and js code for android. And I preparate version control, icon using manifest.xml file after reading your episode. But I could not add admob my project even though my struggle. I could not find any documantation for it. Could yo give me a few advance.Thanks
Well, you need to extend QtActivity to do it and to add admob dependency.
The problem is that the dependency in ant build system in the latest Android SDK is completely broken and adding admob even to a java only android application is not an easy job.
In the future I’ll write another article which will explain all the steps.
Thanks. I’m waiting eagerly.
Thanks a bunch for the articles. Keep them coming. I would like to use QtSerialPort on android with 5.2 is this currently possible? If so, how do you do it. The android version seems to be missing from 5.2. I did manage to compile from the repository but when running it I only got ttyGS0 and ttyUSB0. I did not see any ttyS0 which is what I was expecting. Am I missing something in the manifest file? I have not tried to make one yet. Thanks for any light you can shed on this problem.
I don’t know the status of Qt Serial Port on Android, the guys that are working on it said that it should work. Please check on Interest ML (http://lists.qt-project.org/mailman/listinfo).
Hi,
Thanks for sharing. I make a small app for learning how deploy to store android app but I was encountring trouble problem.When I set the app name from manifest file like that
Application Name:Attetion and Memory
and deploy my device, not change my app name. My project name brain.pro. And When I deploy to my device app name is seem brain. How can I set the project name . Thanks for answer
Did you used QtCreator to create your manifest file? If not then make sure you set “ANDROID_PACKAGE_SOURCE_DIR” qmake variable in your .pro file.
I am chinese. How can I Create an non-full-screen android widget app ? Thanks
Currently you can’t create Android widgets using Qt.
BogDan:
I would love for you to dump out what it takes to communicate via JNI/C++ and edit/insert java code into MainActivity.java and not need to touch ANT.
Many thanks to you for doing all this work.
How to add a third party jar libraries into QtCreator?
Qt Creator has no such an option. You need to do it manually:
– create an android folder, create a libs folder
-copy your .jar files there
– hit run button, ant should add the .jar files to the final .dex file.
More about this topic in 5th episode of the Qt on Android series.
Hi BogDan,
thank you for the helpful blog.
I have a proposal for part 4 or 5 (if you have the time to do it…):
– Interaction between Qt and Android through JNI
Some topics, which should be covered:
– How can I access Java methods from Qt ?
– How can I emit Qt signals from Android intents ?
– Is a Java wrapper always necessary ?
No. 5 will address the JNI stuff,no. 4 will focus on deployment and packaging.
Perfect 🙂
Do you have any rough timeline for the blog release so far ?
I am asking, because I am currently fighting/struggling with the JNI stuff…
I hope this month (early next month) to finish ep. 4 and in may ep. 5.. If you can’t wait until then you can sign up for Paris “Free Qt on Android Coffee and Code Sessions” where I present also the JNI part 🙂
Paris is nice indeed 🙂 Nevertheless, if you are able to share your presentation about this part somewhere… 😉 This would be very helpful. Again, thank you for your support !
Hello again BogDan.
In the past days I put an application in google store. Now I need to update the application. I signed the application at project file, then when I deploy to device, it constantly wanted to password of certificate keystore. Even though entering the correct password is continuously repeats the same thing. I can not sign application. How can I overcome this problem? I created another keystore and try again, the problem continues.
It looks you’ve encountered this https://bugreports.qt-project.org/browse/QTCREATORBUG-11417 bug.
There are a few solutions for you:
– Switch you o.s. locale to english.
– sign the package manually check http://developer.android.com/tools/publishing/app-signing.html#signapp
– wait for Qt SDK 5.3, which fixes the problem.
I managed JNI Integration within my Qt-Application for a science project in my company. The base information I used to do the JNI-Part can be found on the necessitas project page maintained at kde.org. Here is the link to this great tut: http://community.kde.org/Necessitas/JNI
I use the JNI interface for controling Bluetooth smart API on a Nexus 7 via an android service. For data-exchange between java and c/c++ I use a jbyte-array that I convert to a standard c-char-array.
By the way: BogDan, u have done great work for the Qt-world!!
Best Regards Michael
What about android service?
How can I create android service using Qt? Nothing in Qt 5.3 beta!!!
There is no easy way to write an Android service using Qt. The problem is that Qt 5.x has no API to create services. Long time ago in a faraway galaxy there was a Qt Service frameworks (http://doc.qt.digia.com/qtmobility/service-frameworks.html) but it is not available for Qt 5.x. A generic service framework with an Android backend is on my todo list, but I’m afraid it will not be ready sooner than Qt 5.5 (I have other features on my list that must go before services).
You can create an android service and just use Qt code via JNI but is not an easy job …
Ok;
I’m going to do that. Can you guide me? Or show me a start point?
You can start here:
https://www.google.com/search?q=android+services+tutorial
Badly need a tutorial about how to deploy qml extension plugins ..
how about android service with qt have you written something about it as you mentioned?
Useful info. Fortunate me I found your web site accidentally, and I am shocked why this
accident did not happened earlier! I bookmarked it.
can I use WebKit? I have an application that creates on the fly “web pages” for the display of text. I have ported to Qt from IOS for the desktop, now want to port it to android.
If not, could I use Qt libraries from an android App NDK and use the QT string handling routines?
Is source code available?
I am having difficulties understanding AndroidManifest.xml and how it relates to JNI calls. My JNI calls do nothing and I expect my problems are the manifest.
MyJavaClass uses a package name of “com.mycompany.myapp”.
I set my manifest/[@package]=”com.mycompay.myapp”.
What should manifest/application/[@android:name] or manifest/application/activity/[@android.name] should be set to?
My app crashes and fails to run on my device when activity android:name=”com.mycompany.myap.MyJavaClass”?
Any tips on naming and JNI calls are much appreciated.
-Ed
Qt5.3.1
You should set manifest/application/activity/[@android.name] to ”com.mycompany.myap.MyJavaClass” but MyJavaClass MUST extend QtActivity class.
Hi BogDan:
I’m new to the Qt for android,I have trouble in debugging the Qt application for android.The Qt version is 5.3.2(open source),and the versions of android NDK and SDK are r10c and r23.02. after configuration,I open a turtoral appliation(analogclock precisely). the compile and deployment to android device goes smoothly,and the application really works. however, when I try to set a breakpoint and debug it. the application on android device suddenly quit when it hit that breakpoint. If I remove that breakpoint, everything goes well.I don’t know how to handle this issue,can you help me?
Hi,
I need more information about the device. Currently the debugging is not working on devices with Android 5.0.
sorry for late reply, the device runs android 4.2 , and now the problem has been solved.
I have a problem using Qt for android i.e.
Qt5.7.0 and have also added NDK, SDK, JDk and ANT to the Qt Android settings.
While i just try to run a hello world application created by default, it gives a error like
x86_64-linux-android-g++: error: unrecognized command line option ‘-marm’ during Build.
Could you please help me with it.?
Try to use NDK r10e, https://dl.google.com/android/repository/android-ndk-r10e-linux-x86_64.zip
The QT 5.9 version does not have the option of creating your own androidmanifest.xml file like you have. DO you know what happened to it?