Qt for Android Manifest File Configuration | Qt Core (original) (raw)

The Android Manifest is an XML file necessary for any Android app. It contains app configuration for different settings and features that the app uses, as well as details on the app itself, such as, package name, app name, version, etc. Permissions and hardware features can also be set from the manifest.

Qt for Android maintains a version of AndroidManifest.xml with default configuration that include features, permissions and other configuration used by the build system which are needed for building and running Qt apps on Android.

Qt Project to Manifest Configuration

Qt defines some meta-data that is passed from the build systems and to androiddeployqt which populates the manifest with the correct values without explicitly setting these in the manifest file. Such meta-data is assigned a value in the form "-- %%INSERT_VALUE%% --", for example:

<manifest ... android:versionCode="-- %%INSERT_VERSION_CODE%% --" ...

This would be populated with the version code that is set in, for example, CMake.

Qt Default Configuration

Qt sets the following manifest configuration by default:

Section Option Description
package Sets the package name. The default value is org.qtproject.example.app_name.Warning: This field is deprecated and moved to build.gradle. It will be removed in an upcoming release.
android:installLocation Sets the app's installation location, whether internal or external storage. The default value is auto.
android:versionCode Sets the internal version code. Populated from ANDROID_VERSION_CODE (qmake) and QT_ANDROID_VERSION_CODE (CMake). The default value is 1.
android:versionName Sets the public version name. Populated from ANDROID_VERSION_NAME (qmake) and QT_ANDROID_VERSION_NAME (CMake). The default value is 1.0.
Sets the screen sizes that the app supports, default values are anyDensity, largeScreens, normalScreens, and smallScreens.
android:name The application class name. Default value is org.qtproject.qt.android.bindings.QtApplication.
android:label The application name label. Default value is the Qt project's target name. This can be set using QT_ANDROID_APP_NAME.
android:icon The application icon as a reference to a drawable or mipmap resource. This tag is not used unless set using QT_ANDROID_APP_ICON or set manually in the AndroidManifest.xml.
android:hardwareAccelerated Sets hardware acceleration preference. The default value is true.
android:requestLegacyExternalStorage Whether to use Android scoped storage. The default value is true.
android:allowBackup Whether to allow the application to participate in the backup and restore infrastructure. If this is set to false, no backup or restore of the application will ever be performed. The default value is true.
android:fullBackupOnly Whether or not to use Auto Backup on devices where it is available. The default value is false.
android:name The activity class name. The default value is org.qtproject.qt.android.bindings.QtActivity.
android:configChanges Lists configuration changes that the activity handles. Default value is orientation, uiMode, screenLayout, screenSize, smallestScreenSize, layoutDirection, locale, fontScale, keyboard, keyboardHidden, navigation, mcc, mnc, density.
android:launchMode The method used to launch the activity. The default value is singleTop.
android:screenOrientation The orientation of the activity's display on the device. The default value is unspecified.
Specifies the types of intents that the activity can respond to. Default value is
android:exported Sets whether the activity can be launched by components of other applications. The default value is true.

In addition to the default manifest configuration that Qt sets, Qt defines some meta-data that is valid for Qt apps only. Such meta-data is usually under the <activity> section in the form:

The following is a list of such meta-data defined by Qt:

Meta-data Name Description
android.app.lib_name The filename of the native C++ library that is used by the activity.Note: This attribute is mandatory and shouldn't be removed. Default value is the Qt project's target name.
android.app.extract_android_style The method used to extract the native Android Style information. For more information, see Style Extraction. The default value is minimal.
android.app.background_running Sets whether the app keeps running tasks in the background. Setting this to true is the equivalent of setting the environment variable QT_BLOCK_EVENT_LOOPS_WHEN_SUSPENDED to 0. The default value is false. Warning: Setting this to true may cause unexpected crash if the application tries to draw after QGuiApplication::applicationStateChanged() signal is sent with a Qt::ApplicationSuspended state.
android.app.arguments Sets a list of arguments to pass to the app "arg1 arg2". Populated from ANDROID_APPLICATION_ARGUMENTS (qmake) and QT_ANDROID_APPLICATION_ARGUMENTS (CMake). Default value is not set.
android.app.splash_screen_drawable_portrait Sets a drawable for a splash screen specific to portrait mode. For example: android:resource="@drawable/splash_portrait". Default value is not set.
android.app.splash_screen_drawable_landscape Sets a drawable for a splash screen specific to landscape mode. For example: android:resource="@drawable/splash_landscape". Default value is not set.
android.app.splash_screen_drawable Sets a drawable for a splash screen at the start of the app.Note: Orientation specific splash screens are checked first, if not set, this is used instead. For example: android:resource="@drawable/splash". Default value is not set.
android.app.splash_screen_sticky Sets whether the splash screen stays visible until explicitly hidden by the app. For more information, see QAndroidApplication::hideSplashScreen().
android.app.trace_location Specifies a location on device where the application can save tracing files. For example: /storage/emulated/0/Android/data/<app_package_name>/files/. This is needed when using Common Trace Format (CTF) tracing backend.Note: The application needs storage permission for the location. Default: not set.

Application Specific Meta-data

Some meta-data attributes are application-wide, and should be placed under the <application> section:

Meta-data Name Description
android.app.system_libs_prefix Specifies a custom system library path to use for library loading lookup. This is necessary when using Qt libraries installed outside an app's default native (JNI) library directory. The default value is /system/lib/.

Meta-data in Services

Some meta-data attributes can also be used in Services. The main ones are:

Qt Permissions and Features

Different Qt modules might require some Android permissions or features to function properly, for example, Camera permission in QtMultimedia. The androiddeployqt Tool takes care of including such requirements into the Android manifest during the build. Qt defines the following lines into the manifest, which they get replaced by the actual values:

<manifest ... ...

Note: If those lines are removed from the project manifest, Qt won't be able to include the correct permissions. So some functionalities might not work properly.

Customizing Permissions

Since Qt 6.8.1, it is possible to override the default permissions set by Qt modules. This is useful if you need to define the same permissions as used by a Qt module, but with additional or different attributes.

There are two ways to achieve this. First way is to use qt_add_android_permission CMake function in the application's CMakeLists.txt. Permissions defined this way take precedence over the same permissions defined by Qt modules, avoiding duplication.

Second way is to manually define these permissions in the Android manifest file. Permissions defined this way take precedence over permissions set by Qt modules, or set with qt_add_android_permission.

Style Extraction

Qt uses different methods to determine how Qt Widgets and Qt Quick Controls should be styled:

Qt Manifest before 6.2 Release

Versions of Qt earlier than 6.2 used to have an additional set of meta-data defined by Qt. These attributes used to manage dependencies and some were used by the discontinued Ministro service. With Qt 6.2, they should be removed. Here is a list of these attributes:

For more information on the Android Manifest, see Android App Manifest.