1// Copyright (C) 2021 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
5\page android-manifest-file-configuration.html
6\title Qt Android Manifest File Configuration
7\ingroup androidplatform
8\brief Provides details on the AndroidManifest.xml configuration.
9\previouspage android-openssl-support.html
10\nextpage android-services.html
12The Android Manifest is an XML file necessary for any Android app. It contains
13app configuration for different settings and features that the app use, as well
14as details on the app itself, such as, package name, app name, version, etc.
15Permissions and hardware features can also be set from the manifest.
17Qt for Android maintains a version of \c {AndroidManifest.xml} with default
18configuration that include features, permissions and other configuration
19used by the build system which are needed for building and running Qt apps
22\section1 Qt Project to Manifest Configuration
24Qt defines some \l {Android: App Manifest <meta-data>}{meta-data} that is passed
25from the build systems and to \l {Deploying an Application on Android}{androiddeployqt}
26which populates the manifest with the correct values without explicitly setting
27these in the manifest file. Such \l {Android: App Manifest <meta-data>}{meta-data}
28is assigned a value in the form \c {"-- %%INSERT_VALUE%% --"}, for example:
32 android:versionCode="-- %%INSERT_VERSION_CODE%% --"
37This would be populated with the version code that is set in, for example,
40\section1 Qt Default Configuration
42Qt sets the following manifest configuration by default:
50 \li {1, 5} \l {Android: App Manifest <manifest>}{<manifest>}
52 \li Sets the package name. The default value is \c {org.qtproject.example.app_name}.
53 \warning This field is deprecated and moved to \c build.gradle. It will be removed
54 in an upcoming release.
56 \li \c {android:installLocation}
57 \li Sets the app's installation location, whether internal or external storage.
58 The default value is \c auto.
60 \li android:versionCode
61 \li Sets the internal version code. Populated from \c ANDROID_VERSION_CODE (qmake)
62 and \c QT_ANDROID_VERSION_CODE (CMake). The default value is \c 1.
64 \li android:versionName
65 \li Sets the public version name. Populated from \c ANDROID_VERSION_NAME (qmake)
66 and \c QT_ANDROID_VERSION_NAME (CMake). The default value is \c {1.0}.
68 \li \c {<supports-screens>}
69 \li Sets the screen sizes that the app supports,
70 default values are \c anyDensity, \c largeScreens,
71 \c normalScreens, and \c smallScreens.
73 \li {1, 6} \l {Android: App Manifest <application>}{<application>}
75 \li The application class name. Default value is
76 \c {org.qtproject.qt.android.bindings.QtApplication}.
79 \li The application name label. Default value is the Qt project's target name.
81 \li android:hardwareAccelerated
82 \li Sets hardware acceleration preference. The default value is \c true.
84 \li android:requestLegacyExternalStorage
85 \li Whether to use Android scoped storage. The default value is \c true.
87 \li android:allowBackup
88 \li Whether to allow the application to participate in the backup and restore
89 infrastructure. If this is set to \c false, no backup or restore of the
90 application will ever be performed. The default value is \c true.
92 \li android:fullBackupOnly
93 \li Whether or not to use Auto Backup on devices where it is available.
94 The default value is \c false.
96 \li {1, 6} \l {Android: App Manifest <activity>}{<activity>}
98 \li The activity class name. The default value is \c {org.qtproject.qt.android.bindings.QtActivity}.
100 \li android:configChanges
101 \li Lists configuration changes that the activity handles. Default value is
102 \c orientation, \c uiMode, \c screenLayout, \c screenSize,
103 \c smallestScreenSize, \c layoutDirection, \c locale, \c fontScale,
104 \c keyboard, \c keyboardHidden, \c navigation, \c mcc, \c mnc, \c density.
106 \li android:launchMode
107 \li The method used to launch the activity. The default value is \c singleTop.
109 \li android:screenOrientation
110 \li The orientation of the activity's display on the device. The default value is \c unspecified.
113 \li Specifies the types of intents that the activity can respond to. Default value is
115 <action android:name="android.intent.action.MAIN"/>
116 <category android:name="android.intent.category.LAUNCHER"/>
120 \li Sets whether the activity can be launched by components of other applications.
121 The default value is \c true.
124\section1 Qt Specific Meta-data
126In addition to the default manifest configuration that Qt sets, Qt defines
127some meta-data that is valid for Qt apps only. Such meta-data is usually
128under the \c <activity> section in the form:
132 android:name="meta-data-name"
133 android:value="meta-data-value" />
136The following is a list of such meta-data defined by Qt:
143 \li android.app.lib_name \target android.app.lib_name
144 \li The filename of the native C++ library that is used by the activity.
145 \note This attribute is mandatory and shouldn't be removed.
146 Default value is the Qt project's target name.
148 \li android.app.extract_android_style
149 \li The method used to extract the native Android Style information.
150 For more information, see \l {Style Extraction}.
151 The default value is \c minimal.
153 \li android.app.background_running \target android.app.background_running
154 \li Sets whether the app keeps running tasks in the background.
155 Setting this to \c true is the equivalent of setting the environment
156 variable \c QT_BLOCK_EVENT_LOOPS_WHEN_SUSPENDED to \c 0.
157 The default value is \c false.
159 \warning Setting this to \c true may cause unexpected crash if the
160 application tries to draw after \l {QGuiApplication::applicationStateChanged()}
161 signal is sent with a \l {Qt::ApplicationSuspended} state.
163 \li android.app.arguments \target android.app.arguments
164 \li Sets a list of arguments to pass to the app \c {"arg1 arg2"}.
165 Populated from \c ANDROID_APPLICATION_ARGUMENTS (qmake) and
166 \c QT_ANDROID_APPLICATION_ARGUMENTS (CMake).
167 Default value is not set.
169 \li android.app.splash_screen_drawable_portrait
170 \li Sets a drawable for a splash screen specific to portrait mode.
171 For example: \c {android:resource="@drawable/splash_portrait"}.
172 Default value is not set.
174 \li android.app.splash_screen_drawable_landscape
175 \li Sets a drawable for a splash screen specific to landscape mode.
176 For example: \c {android:resource="@drawable/splash_landscape"}.
177 Default value is not set.
179 \li android.app.splash_screen_drawable
180 \li Sets a drawable for a splash screen at the start of the app.
181 \note Orientation specific splash screens are checked first,
182 if not set, this is used instead.
183 For example: \c {android:resource="@drawable/splash"}.
184 Default value is not set.
186 \li android.app.splash_screen_sticky
187 \li Sets whether the splash screen stays visible until explicitly hidden
189 For more information, see
190 \l {QNativeInterface::}{QAndroidApplication::hideSplashScreen()}.
192 \li android.app.trace_location
193 \li Specifies a location on device where the application can save tracing files.
194 For example: /storage/emulated/0/Android/data/<app_package_name>/files/.
195 This is needed when using Common Trace Format (CTF) tracing backend.
196 \note The application needs storage permission for the location.
200\section2 Application Specific Meta-data
202Some meta-data attributes are application-wide, and should be placed under
203the \c <application> section:
210 \li android.app.system_libs_prefix \target android.app.system_libs_prefix
211 \li Specifies a custom system library path to use for library loading lookup.
212 This is necessary when using Qt libraries installed outside an app's
213 default native (JNI) library directory.
214 The default value is \c {/system/lib/}.
217\section2 Meta-data in Services
219Some meta-data attributes can also be used in \l {Android Services}{Services}.
223 \li \l {android.app.lib_name}
224 \li \l {android.app.background_running}
225 \li \l {android.app.arguments}
228\section2 Qt Permissions and Features
230Different Qt modules might require some Android permissions or features to
231function properly, for example, Camera permission in \l {QtMultimedia}.
232l{The androiddeployqt Tool} takes care of including such requirements into the
233Android manifest during the build. Qt defines the following lines into the
234manifest, which they get replaced by
239 <!-- %%INSERT_PERMISSIONS -->
240 <!-- %%INSERT_FEATURES -->
245\note If those lines are removed from the project manifest, Qt won't be
246able to include the correct permissions. So some functionalities
247might not work properly.
249\section2 Style Extraction
251Qt uses different methods to determine how Qt Widgets and Qt Quick Controls
255 \li \c default or \c full: when using Qt Widgets or Qt Quick Controls 1.
256 \note This method uses some Android non-SDK interfaces, that are being
257 restricted and removed by Google starting from Android 9.0 (API 28).
258 For that reason, this is not recommended for Android 9.0 or greater.
259 \li \c minimal: when using Qt Quick Controls 2 and no Qt Widgets or Qt Quick
260 Controls 1. This is faster than using the default or full options.
261 \li \c none: no style extraction.
264\section1 Qt Manifest before 6.2 Release
266Versions of Qt earlier than 6.2 used to have an additional set of meta-data
267defined by Qt. These attributes used to manage dependencies and some were
268used by the discontinued \c Ministro service. With Qt 6.2, they should be removed.
269Here is a list of these attributes:
272 \li android.app.qt_sources_resource_id
273 \li android.app.repository
274 \li android.app.bundled_libs_resource_id
275 \li android.app.bundle_local_qt_libs
276 \li android.app.use_local_qt_libs
277 \li android.app.libs_prefix
278 \li android.app.load_local_libs_resource_id
279 \li android.app.load_local_jars
280 \li android.app.static_init_classes
281 \li android.app.qt_libs_resource_id
282 \li android.app.ministro_not_found_msg
283 \li android.app.ministro_needed_msg
284 \li android.app.fatal_error_msg
287For more information on the Android Manifest, see
288\l{Android: App Manifest}{Android App Manifest}.