diff options
Diffstat (limited to 'doc/src/deployment/deployment.qdoc')
| -rw-r--r-- | doc/src/deployment/deployment.qdoc | 316 |
1 files changed, 0 insertions, 316 deletions
diff --git a/doc/src/deployment/deployment.qdoc b/doc/src/deployment/deployment.qdoc index e50256199..a56276853 100644 --- a/doc/src/deployment/deployment.qdoc +++ b/doc/src/deployment/deployment.qdoc @@ -124,319 +124,3 @@ \sa {Deploying Translations} */ - -/*! - \page deployment-android.html - - \title Deploying an Application on Android - - This article gives a technical description of the steps required to take - any given Qt application and deploy it to an Android device (or market place). - - It is recommended that you use Qt Creator or the Makefile created by qmake to - create the application bundle. The following information will give you a technical - insight into the structure of the resulting Android application which is not normally - required just to write an application. - - All the steps described here are handled automatically by the build script and - the \l {androiddeployqt}{androiddeployqt deployment tool}, which are run by Qt Creator - for you. - - \note If you prefer building Android packages from the command line, you may use the "aab" - or "apk" build targets in the Makefile directly: - - \code - % make aab - \endcode - - or - - \code - % make apk - \endcode - - \tableofcontents - - \section1 The Application Bundle - - Applications on Android can be packaged in two ways: Either as Application Package (APK) - or Android App Bundle (AAB). Both are ZIP files which follow a predefined directory - structure. The difference between the two is that APK files can be downloaded to - and executed on a device. AAB, on the other hand, is intended to be interpreted by the - Google Play store and is used to generate APK files. - - For testing the application locally, the APK format is the most appropriate, as this can - be uploaded directly to the device and run. For distribution to the Google Play store, it is - recommended that you use AAB instead, which has a similar layout. The added convenience - of AAB is that you can include all target ABIs in the same bundle without increasing the - size of the actual package downloaded by your users. When using AAB, the Google Play store - generates optimized APK packages for the devices issuing the download request and - automatically sign them with your publisher key. - - Read \l{https://developer.android.com/guide/app-bundle}{the Android documentation} if you - want to know more about the AAB format. - - In either case, the files must be copied into a special directory structure first, before - bundling them in a single ZIP file - - This contains one or more binary \c .so files with the code for your application, as - well as any dependencies, such as Qt's libraries and plugins. In addition, it includes - \c .jar files containing compiled Java code, assets, resources, and some \c .xml - files that are used to describe the contents of the bundle. - - \section1 Package Template - - A template for the other sources of an APK package is contained in \c{$QTDIR/src/android/templates}. - The first step of making a package manually is to copy these files into an empty directory. In this - guide, we'll refer to this build directory as \c{$BUILD_TARGET}. - - We also need to make sure the application binary is copied into the package. This can be - achieved by using the following command after running qmake on your application's project file: - - \code - make install INSTALL_ROOT=$BUILD_TARGET - \endcode - - It will copy the application binary and any other installation requirements into the packaging - directory. - - The packaging directory will now consist of the following parts: - - \section2 AndroidManifest.xml - - The \c{AndroidManifest.xml} file gives detailed meta-information about your application. This - information is used for several things. It is used by the target device to decide which features - to enable, the default orientation of the application, and so on. In addition, it's used by the - market place for information on the version code, device support, package name, and lots more. - - For more information about general capabilities of and requirements for the - \c{AndroidManifest.xml} file, please refer to the - \l{http://developer.android.com/guide/topics/manifest/manifest-intro.html}{Android documentation on this topic}. - - The default manifest contains some special parameters used by Qt to set up the application for - running. When you are creating your own Android manifest, you must make sure that it contains these - parameters. The \c androiddeployqt tool replaces content in the template with the correct - values. - - \section2 Java Code - - Under \c{$BUILD_TARGET/src} are the files comprising the Java code of the Android application. - The regular Android application launcher is a Java process, so Qt applications have a - Java-based entry point. The code in here will load the required Qt libraries, based on the - meta-information given in other files in the template. - - After loading the libraries, the Java code will call into the application's native \c{main()} - function on a new thread and the application will launch. At this point, the Java code in - the template is used to delegate events from Android into Qt. - - One thing to note about the files in this directory is that they can contain code specific - to certain Android versions. Based on the minimum required Android API level of your - application it might be necessary to remove some of this code. This is done automatically - by \c androiddeployqt and Qt Creator during packaging. - - For example, lets say the code contains the following: - - \code -//@ANDROID-21 - @Override - public void onActivityReenter(int resultCode, Intent data) - { - // Do something - return super.onActivityReenter(resultCode, data); - } -//@ANDROID-21 - \endcode - - If your minimum Android API level is 20 or lower, the code is removed before - building, since it's not a supported API on Android API level 20. However, if your minimum API - level is 21 or higher, it is left in. - - \section2 Resources - - Under the \c{res/} folder in the \c{$BUILD_TARGET} are Android resources that can be accessed - from the \c{AndroidManifest.xml} and Java code of your application. A typical example of - resources which should be placed here are the icon files used by the application launcher to - represent your application. - - In Qt, some translations used for the Ministro service and some files with meta-information - are in the default resources of the application. - - \section3 res/values/libs.xml - - One of the files containing meta information about the deployment of the application is - \c{libs.xml}. It consists of the following values: - - \list - \li \c{qt_sources}: The URL of one or more Ministro repositories that contain the - necessary Qt libraries. This is used when the Ministro deployment mechanism is active. Read the - \l{http://necessitas.kde.org/necessitas/ministro.php}{Ministro documentation} for more - information about such repositories. - \li \c{bundled_libs}: Libraries in the package's library folder which should be loaded on start-up. - Library names should be specified without the \c lib prefix and \c{.so} suffix. - \li \c{qt_libs}: Qt libraries which should be loaded on start-up. When bundled deployment is - used, these are expected to be found inside the \c{APK}'s library folder. When Ministro - deployment is in use, they are requested from the Ministro service on the device. And when - debugging deployment is in use, they are loaded from the \c{/data/local/tmp/qt} directory on the - target device. - \endlist - - \section3 res/values/strings.xml - - The \c{strings.xml} file contains some strings used by the \c{AndroidManifest.xml} and by the - deployment mechanisms, as well as some strings used when loading the Ministro service. - - In particular, the application name and the name of the application binary can be specified - here. There are also strings that contain additional libraries that should be loaded and - \c JAR files which should be included in the class path. The latter is only used for deployment - with Ministro or debug deployment. - - \section2 Libraries - - Under \c libs in the package directory, it's possible to place libraries that should be included - in the application bundle. \c JAR libraries should be placed directly under \c{libs/}, while - shared libraries should be put in a subdirectory suitably named after the target ABI - of the libraries. - - \section1 Building the Android Application Package - - The project can be built using the gradle tool. If an APK intended for release is built, then - it should be signed and aligned using \c jarsigner and \c zipalign. - - \section1 androiddeployqt - - Building an application package is complex, so Qt comes with a tool which handles the work for - you. The steps described in this document so far are handled automatically by the tool. - - In addition, there are Makefile build targets for building the package from the - command line. There is also automated support in Qt Creator for generating both \c APK and \c AAB - packages. - - \section2 Required Steps Before Running androiddeployqt - - Before running the tool manually, you need to run \c qmake and \c make on your project. Running - \c qmake creates the \c Makefile, and it will also generate a \c JSON file containing important - settings used by \c androiddeployqt. - - You should then install the application binary (and any other requirements) into the library - folder of the \c bundle. If \c{$BUILD_TARGET} is your build directory (the first time you do this, - the directory should be empty at this point), then you can install the binary with the following - command: - - \code - % make install INSTALL_ROOT=$BUILD_TARGET - \endcode - - \section2 Command Line Arguments - - The only required command line argument when running the tool is \c{--output}. This should - be set to \c{$BUILD_TARGET}, that is: the build directory where you installed your application - binary. - - Other command line arguments are optional but useful. Here's a quick overview. More information - is available by passing the \c{--help} argument to androiddeployqt. - - \list - \li \c{--aab}: Generate an Android Application Bundle, rather than an APK. Note that this - invalidates some of the other arguments, such as --install. - \li \c{--input <file name>}: This allows you to specify the \c JSON file generated by \c qmake. - By default, \c androiddeployqt will try to guess the file name based on the current working - directory. - \li \c{--deployment <mechanism>}: Specify this to pick a different deployment mechanism than the - default. - \li \c{--install}: Specify this to install the finished package on the target device or - emulator. Note that if a previous version of the package is already installed, it will be - uninstalled first, removing any data it might have stored locally. - \li \c{--device <ID>}: Specify the ID of the target device or emulator as reported by the \c adb - tool. If an ID is specified, it will be passed to all calls to \c adb. If it is unspecified, no - particular device or emulator will be requested by \c adb, causing it to pick a default instead. - \li \c{--android-platform <platform>}: The SDK platform used for building the Java code of the - application. By default, the latest available platform is used. - \li \c{--release}: Specify this to create a release package instead of a debug package. With no - other arguments, release packages are unsigned and cannot be installed to any device before - they have been signed by a private key. - \li \c{--sign <url> <alias>}: Sign the resulting package. Specifying this also implies - \c{--release}. The URL of the keystore file and the alias of the key have to be specified. In - addition, there are a number of options that can be specified which are passed through to the - \c jarsigner tool. Pass \c{--help} to \c androiddeployqt for more information about these. - \li \c{--jdk <path>}: Specify the path to the Java Development Kit. This is only required for - signing packages, as it is only used for finding the \c jarsigner tool. If it is unspecified, - then \c androiddeployqt will attempt to detect \c jarsigner, either using the \c{JAVA_HOME} - environment variable, or on the \c PATH. - \li \c{--verbose}: Specify this to output more information about what \c androiddeployqt is - doing. - \endlist - - \section1 Dependencies Detection - - Qt comes with a number of plugins which are loaded at run-time when they are needed. These - can handle anything from connecting to SQL databases to loading specific image formats. - Detecting plugin dependencies is impossible as the plugins are loaded at run-time, but - androiddeployqt tries to guess such dependencies based on the Qt dependencies - of your application. If the plugin has any Qt dependencies which are not also dependencies of - your application, it will not be included by default. For instance, in order to ensure that - the SVG image format plugin is included, you will need to add \c{QT += svg} to your \c .pro file - so that the \l{Qt SVG} module becomes a dependency of your application. - - If you are wondering why a particular plugin is not included automatically, you can run androiddeployqt - with the \c --verbose option to get the list of missing dependencies for each excluded plugin. You - can achieve the same in Qt Creator by ticking the \gui{Verbose output} check box in the - \gui{Deployment configurations}. This is located in the \gui{Run} tab of your \gui{Projects} - settings. - - It's also possible to manually specify the dependencies of your application. See the documentation - for the \c{ANDROID_DEPLOYMENT_DEPENDENCIES} qmake variable below. - - \section1 Android-specific qmake Variables - - Unless the project has special requirements such as third party libraries, it should be - possible to run \c androiddeployqt on it with no modifications and get a working Qt for Android - application as a result. - - However, there are a set of \c qmake variables that can be used to tailor your package. At some - point during development, you will most likely want to look into these variables, as they will - e.g. allow you to set the name of your application as it appears in the application menu on - devices. - - Here is a list of some variables that are particularly interesting when making Android - applications: - - \list - \li \c{ANDROID_DEPLOYMENT_DEPENDENCIES}: By default, \c androiddeployqt will detect the - dependencies of your application. But since run-time usage of plugins cannot be detected, there - could be false positives, as your application will depend on any plugins that are \e potential - dependencies. If you want to minimize the size of your \c APK, it's possible to override the - automatic detection using the \c{ANDROID_DEPLOYMENT_DEPENDENCIES} variable. This should contain - a list of all Qt files which need to be included, with paths relative to the Qt install root. - Note that only the Qt files specified here will be included. Failing to include the correct - files can result in crashes. It's also important to make sure the files are listed in the - correct loading order. This variable provides a way to override the automatic detection - entirely, so if a library is listed before its dependencies, it will fail to load on - some devices. - \li \c{ANDROID_PACKAGE_SOURCE_DIR}: This variable can be used to specify a directory where - additions and modifications can be made to the default Android package template. The - \c androiddeployqt tool will copy the application template from Qt into the build directory, and - then it will copy the contents of the \c{ANDROID_PACKAGE_SOURCE_DIR} on top of this, overwriting - any existing files. The update step where parts of the source files are modified automatically - to reflect your other settings is then run on the resulting merged package. If you, for - instance, want to make a custom \c{AndroidManifest.xml} for your application, then place this - directly into the folder specified in this variable. You can also add custom Java files in - \c{ANDROID_PACKAGE_SOURCE_DIR/src}. - \note When adding custom versions of the build files (like strings.xml, libs.xml, - AndroidManifest.xml, etc.) to your project, make sure you copy them from the package template, - which is located in \c{$QT/src/android/java}. You should never copy any files from the build - directory, as these files have been altered to match the current build settings. - \li \c{ANDROID_EXTRA_LIBS}: A list of external libraries that will be copied into your application's - library folder and loaded on start-up. This can be used, for instance, to enable OpenSSL - in your application. Simply set the paths to the required \c{libssl.so} and \c{libcrypto.so} - libraries here and OpenSSL should be enabled automatically. - \li \c{ANDROID_EXTRA_PLUGINS}: This variable can be used to specify different resources that your - project has to bundle but cannot be delivered through the assets system, such as qml plugins. When - using this variable, \c androiddeployqt will make sure everything is packaged and deployed properly. - \endlist - - \section1 Deployment in Qt Creator - - Qt Creator will run the \c androiddeployqt tool for you, and provides easy and intuitive user - interfaces to specify many of the options. For more information, see - \l{Qt Creator: Deploying Applications to Android Devices}{the Qt Creator documentation}. -*/ |