diff options
author | Assam Boudjelthia <assam.boudjelthia@qt.io> | 2020-04-03 17:33:15 +0300 |
---|---|---|
committer | Assam Boudjelthia <assam.boudjelthia@qt.io> | 2020-04-07 10:57:54 +0300 |
commit | d9b39705b08defd13ba351644666da0ecf5e6189 (patch) | |
tree | 8ada673b6bb61cde039c882fbf2353346e62cb4c | |
parent | a86bcb6bc3b3a2cdbed07befe98d967968f638fe (diff) |
Android: move and re-organize android docs to separate platforms/androidv5.15.0-beta4
For better organization this re-structures each doc item to separate
file and under separate directory in platforms/android.
Task-number: QTBUG-80390
Change-Id: I3307daf3188772a0504d2ed6ec4016dd493be0cf
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
-rw-r--r-- | doc/src/deployment/deployment.qdoc | 316 | ||||
-rw-r--r-- | doc/src/platforms/android.qdoc | 497 | ||||
-rw-r--r-- | doc/src/platforms/android/android-3rdparty-libs.qdoc | 88 | ||||
-rw-r--r-- | doc/src/platforms/android/android-building.qdoc (renamed from doc/src/platforms/android-building.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/platforms/android/android-deploying-application.qdoc | 342 | ||||
-rw-r--r-- | doc/src/platforms/android/android-openssl-support.qdoc | 92 | ||||
-rw-r--r-- | doc/src/platforms/android/android-platform-notes.qdoc (renamed from doc/src/platforms/android-platform-notes.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/platforms/android/android-publishing-to-googleplay.qdoc | 94 | ||||
-rw-r--r-- | doc/src/platforms/android/android-services.qdoc | 64 | ||||
-rw-r--r-- | doc/src/platforms/android/android.qdoc | 205 | ||||
-rw-r--r-- | doc/src/platforms/android/examples-android.qdoc (renamed from doc/src/examples-android.qdoc) | 0 | ||||
-rw-r--r-- | doc/src/platforms/android/porting-to-android.qdoc | 88 |
12 files changed, 973 insertions, 813 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}. -*/ diff --git a/doc/src/platforms/android.qdoc b/doc/src/platforms/android.qdoc deleted file mode 100644 index b9d10cadc..000000000 --- a/doc/src/platforms/android.qdoc +++ /dev/null @@ -1,497 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2019 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page android.html -\title Qt for Android -\brief Provides information about Android support in Qt. -\ingroup supportedplatform - -Qt for Android enables you to run Qt 5 applications on Android devices. -All Qt modules (essential and add-on) are supported except Qt \WebEngine, -Qt Serial Port, and the platform-specific ones (Qt Mac Extras, -Qt Windows Extras, and Qt X11 Extras). - -The following configurations are supported: - -\include supported-platforms.qdocinc android - -\br -The following list summarizes what you can do with Qt for Android: - -\list - \li Run \l{Qt Widgets}{Widget} and - \l{QML Applications}{QML} applications on the device - or emulator. - \li Support for native \l{Android Style}{Android style} with - Qt Quick Controls. - \li Handle \l{Qt Multimedia}{Multimedia} content in your Qt Quick 2 - applications. - \li Get \l{Qt Sensors}{sensor} readings and react to the changes. - \li Retrieve current position data using satellite and network - information. - \li Connect and exchange data with \l{Qt Bluetooth}{Bluetooth} - and \l{Qt NFC}{NFC}-enabled devices. - \li Integrate Java code into your application using - \l{Qt Android Extras}. - \li Develop secure applications using OpenSSL library. - \li Create \l{Android Services} - \li Create and deploy Application Package using Qt Creator. -\endlist - -The following topics provide more details about how to use Qt for Android: -\list - \li \l{Getting Started with Qt for Android}{Getting Started} - \li \l{Qt for Android - Building from Source} - \li \l{Porting to Android}{Porting a Qt Application} - \li \l{Qt for Android Examples}{Examples} - \li \l{Adding OpenSSL Support for Android} - \li \l{Android Services}{Creating Android Services} - \li \l{Third-party Android Libraries}{Including third-party Android libraries in an application} - \li \l{Qt Creator: Deploying Applications to Android Devices}{Deploying to the Device} - \li \l{Publishing to Google Play} - \li \l{Platform and Compiler Notes - Android}{Platform Notes} - \li \l{Android GNU C++ run-time licensing} -\endlist -*/ - -/*! - \page android-3rdparty-libs.html - \title Third-party Android Libraries - \brief Provides instructions to include third-party Android libraries in an application. - - This guide describes how to include a Java-based third-party library in your application package. - There are many Java libraries which provide APIs that may be useful to your application. - One example is the \c{Google Play Services} add-on provided in the Android SDK. We will use this library - as an example in this guide, but the same approach may be taken to include other libraries, provided - that they have been made to be included as library projects in an Android application. - - \section1 Prerequisites - - This guide assumes that the \l{androiddeployqt} tool is used for constructing the deployment package. - When using Qt Creator for building and deploying, androiddeployqt is used behind the scenes, so this also - applies to development with Qt Creator. Explaining how to access the Java APIs after they have been - included in the application is not in the scope of this guide. - - \section1 Including the Library in the Source - - The very first thing we need to do is to copy the actual library project into the source of our - project. We want the contents of the library project to be copied without modifications into the - packaging directory, so we need to place it into the \c{Android Package Source Directory}. This - can be any directory which is pointed to by the \l{qmake} variable \c{ANDROID_PACKAGE_SOURCE_DIR}. - - If you are using Qt Creator, you can quickly set up the directory structure by clicking on the - \gui{Create AndroidManifest.xml} button in the \gui{Deployment} settings of your project. This - will create an \c{Android Package Source Directory} and place the \c{AndroidManifest.xml} file - inside it. Copy the library project directory into this directory. - - For example, once it has been installed via the \c{Android SDK Maintenance} application, - the \c{Google Play Services} library project is located under the path - \c{$ANDROID_SDK_ROOT/extras/google/google_play_services/libproject/google-play-services_lib}. If - the \c{Android Package Source Directory} of our project is \c{$PROJECT_ROOT/android}, then we - can copy the \c{google-play-services_lib} directory in there, creating - \c{$PROJECT_ROOT/android/google-play-services_lib}. - - \section1 Adding the Library to the Project Dependencies - - Once the library code has been copied into the project, we need to tell the Android build system - about it. This is done in the \c{project.properties} file. Create a file called \c{project.properties} - inside the \c{Android Package Source Directory} and add a line to it which assigns the relative - path of the library project to the property \c{android.library.reference.1}. If you want to include - multiple library projects, increment the counter at the end of the property name for each. - - In our example, we would create \c{$PROJECT_ROOT/android/project.properties} and add the - following contents: - - \badcode - android.library.reference.1=google-play-services_lib/ - \endcode - - \section1 Deployment - - And that's it: Provided that the path referenced in the \c{project.properties} file is located - under the \c{Android Package Source Directory}, the deployment tool will copy it into the - packaging directory and perform the necessary steps to include it in your \c{APK} or \c{AAB}. - You can now add Java code to your application which accesses the APIs provided by the library - project. - -*/ - -/*! -\page android-getting-started.html -\title Getting Started with Qt for Android -\brief Provides instructions to install and configure your development environment. - -\section1 Installing the Prerequisites - -In order to use \l{Qt for Android}, you need the following: - -\list -\li \l{http://developer.android.com/sdk/index.html}{The Android SDK Tools} - \note If your Qt version is earlier than v5.9, use the SDK tools package - v25.2.5 or earlier. -\li \l{http://developer.android.com/tools/sdk/ndk/index.html}{The Android NDK} - \list - \li Qt 5.11 and below - \list - \li NDK r10e - \li GCC toolchain - \endlist - \li Qt 5.12.0 to 5.12.5 - and Qt 5.13.0 to 5.13.1 - \list - \li NDK r19c - \li \e android-clang - \endlist - \li Qt 5.14+, Qt 5.13.2+ - and Qt 5.12.6+ - \list - \li NDK r20b or r21 - \li \e android-clang - \li \note Qt 5.14.0 and 5.14.1 with NDK r21 have a bug fixed at \l{https://bugreports.qt.io/browse/QTBUG-81461}{QTBUG-81461}. - \endlist - \endlist - -\li \l{http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html}{Java SE Development Kit} (JDK) v6 or later. You can also use \l{http://openjdk.java.net}{OpenJDK} on Linux. -\endlist - -After installing these tools, update the Android SDK by installing the API -and build tools packages required for development. You can install these packages -either through Android Studio or using the command line tools package you installed -earlier. For more details, refer to the -\l{https://developer.android.com/studio/intro/update.html}{Android Studio} -documentation. - -\note Make sure to unpack the Android SDK and NDK to a writeable location that Qt Creator -can access later. Otherwise, Qt Creator won't be able to use \c sdkmanager or find all -components even if they were installed manually. - -\section2 Updating the Android SDK - -The command line tools provided by the Android SDK Tools package also enables updating -the SDK, but without a GUI. For example, the following command on Ubuntu updates the SDK -by installing the latest \c build-tools, \c platform-tools, \c emulator, and \c patcher -packages: - -\badcode -./bin/sdkmanager --update -\endcode - -To install a specific package, use \c sdkmanager from -\c{<ANDROID_SDK_ROOT>/tools/bin}. For example, the following command installs the -\c android-10 platforms package on Ubuntu: - -\badcode -./sdkmanager "platforms;android-10" -\endcode - -For more details, refer to the -\l{https://developer.android.com/studio/command-line/sdkmanager.html}{sdkmanager} -documentation. - -\section1 Configuring Your Development Host - -\section2 Windows - -The default USB driver on Windows does not allow debugging using -Android Debug Bridge (ADB) tool. You must install the additional USB driver -provided by the \e extras Android SDK package. Use the following command from -the Windows command prompt to install the extras package: - -\badcode -sdkmanager.bat "extras;google;usb_driver" -\endcode - -After the package installation is complete, install the driver from -\c{<ANDROID_SDK_ROOT>/extras/google/usb_driver}. Try running a few basic -\l{http://developer.android.com/tools/help/adb.html}{adb} commands now -and check whether your Android device responds to it. - -\section2 64-bit Linux - -If you're developing on a 64-bit Linux machine, you must install the -following dependencies in order to run 32-bit executables like \c adb, which -allows Qt Creator to find devices to deploy to: - -\badcode -sudo apt-get install libstdc++6:i386 libgcc1:i386 zlib1g:i386 libncurses5:i386 -\endcode - -To run the emulator, the following dependencies are also necessary: - -\code -sudo apt-get install libsdl1.2debian:i386 -\endcode - -\section2 Qt Creator IDE - -The Qt Creator IDE that came with the Qt 5 installation on your development -host, must be configured to enable developing applications for Android. Launch -Qt Creator and select \uicontrol Tools > \uicontrol Options > -\uicontrol Devices > \uicontrol Android to add the Android NDK and SDK paths. -For more details, refer to \l{Qt Creator: Connecting Android Devices}{Qt Creator Manual}. - -\section1 Testing Your Setup - -Now you can test your development setup by running the examples that came -with the Qt 5 installation. You can browse these examples in -Qt Creator \uicontrol Welcome mode. Use the \c android filter in the search -field to list all the examples tested on Android. - -To develop a simple application from scratch, see \l{Creating a Mobile Application}. -*/ -/*! -\page porting-to-android.html -\title Porting to Android -\brief Provides instructions to port your existing Qt application to Android. - -In this section, we are going to port an existing Qt Application to -\l{Qt for Android}{Android} and deploy it to the device. - -Most Qt applications should be portable to Android with ease, unless they -depend on a specific hardware or software feature not supported by Android. -If your application is not using any such feature, deployment is probably the -only step that demands some changes to your application. - -\include porting-notes.qdocinc using resources - -The other approach is to deploy the resources into the package's \c{assets} -directory. It is the best option if you want to achieve better -interoperability with the Android APIs. You can access all resources in the -directory using the "assets:" prefix. Unlike qrc, this approach is not a -cross-platform solution. - -The following step-by-step instructions guide you to port an existing Qt Quick -application to Android using the qrc approach: - -\list 1 - \li Open the existing project in Qt Creator and configure it - with "Android for ARM" kit. For more information, see - \l{Qt Creator: Configuring Projects} - \li Identify all the resources used by your application and add them to one - or more qrc files. - Qt Creator updates your qmake project file with the "RESOURCES" - variable listing the qrc files you added. - \li To load or refer to the resources in the qrc file from your C++ code, - use the "qrc:" scheme followed by the absolute URL. For example, to - load the \c{main.qml} file from \c{resources.qrc}, you can use the - following C++ code: - - \code - QQuickView viewer; - viewer.setSource(QUrl("qrc:/qml/main.qml")); - viewer.show(); - \endcode - - \note QML documents can refer to the contents in qrc files using the - relative path to the document. Such references do not require the - "\c{qrc:}" or "\c{:/}" prefix. - \li Save the changes to your project and run the application. -\endlist - -\note Qt Quick Controls in the application will use native -\l{Android Style}{Android style} if the target device is running -Android 3.0 (API 11) or later. The application should function normally on -devices with Android versions earlier than v3.0, but without native style for -controls. - -Qt Creator deploys your application on the Android device, if the -device is detected by the PC. Otherwise, it tries to run the application on an -AVD (Android Virtual Device). You will be prompted to create one if there are no -AVDs found. -*/ - -/*! -\page android-openssl-support.html -\title Adding OpenSSL Support for Android -\brief Provides instructions to package OpenSSL libraries with your Qt application for Android. - -The Qt installation package comes with OpenSSL support but the OpenSSL libraries -are not part of the package due to legal restrictions in some countries. If your -application depends on OpenSSL, consider packaging the SSL libraries with your -Application Package (APK) as the target device may or may not have them. You -can use the \l{QSslSocket::supportsSsl()} static function to check for SSL -support on the target. - -The following instructions guide you to build and add the OpenSSL libraries to -the APK: -\list 1 - \li Download the latest OpenSSL 1.1.x sources from \l{http://www.openssl.org/source}. - - \li Extract the sources to a folder and navigate to that folder using - the CLI. - \note If your development platform is Windows, you need \c msys with - \c perl v5.14 or later to build OpenSSL. - - \li Add android llvm toolchain to your path: - \badcode - export PATH="<android_ndk_path>/toolchains/llvm/prebuilt/<host>/bin":$PATH - \endcode - - \li Configure the OpenSSL sources to build for Android using - the following command: - - \badcode - ./Configure shared android-<arch> -D__ANDROID_API__=21 - \endcode - - \note You must consider enabling/disabling the SSL features based on the - legal restrictions in the region where your application is available. - See the \l{OpenSSL Configure Options}{SSL configure options} for details about - the configurable features. - - \li Run \c{make SHLIB_VERSION_NUMBER= SHLIB_EXT=_1_1.so build_libs} to - build \c libcrypto and \c libssl shared libraries that are not versioned, - but with a \e _1_1 suffix. If you want to use a different suffix, then you must - set the \c ANDROID_OPENSSL_SUFFIX environment variable before you access the - Qt Network API. Without a suffix, Android 5 (API 21) will load the system - libraries \e libcrypto.so and \e libssl.so, which are OpenSSL 1.0, rather than - your libraries. - - \note Android does not load versioned libraries. - - \li Open your Qt project using Qt Creator and update the "Build Android APK" - settings to add \e libcrypto and \e libssl as additional libraries for - your project. - - \li Run your application to see it running on the device. -\endlist - -\note here \l{https://github.com/KDAB/android_openssl} you can find a script which -can be used to compile openssl for all android abis and also latest prebuilt libs. - -Qt Creator builds your application and creates an application package (APK) -with the OpenSSL libraries bundled in it. Once the APK is ready, it uses \c adb -to deploy the APK on the target you chose and launch the application. - -*/ - -/*! -\page android-publishing-to-googleplay.html -\title Publishing to Google Play -\brief Provides instructions to prepare your application for publishing. - -\l{Qt for Android} provides a complete solution to develop, build, and package -your applications for Android. Most of these tasks, especially packaging and -deployment are handled by Qt Creator providing rich developer experience. - -Every time you run the application using Qt Creator, an Android Application -Package (APK) is created and deployed onto the target (device or emulator) you -choose. With some minor changes to how the \e .apk is created, you can publish -your application on Google Play and monetize. The following -step-by-step instructions guide you to create an \e{.apk} that can go live -on Google Play: -\list 1 - \li Open your application project using Qt Creator v3.0 or later and change - its \uicontrol Build settings to build release version. - - \li Select \uicontrol {Create Templates} under \uicontrol Build settings to - create the template files such as \e AndroidManifest.xml and other - resources. - - \note You can edit the \e AndroidManifest.xml in \uicontrol General or - \uicontrol {XML Source} mode. - - \li Check for the following in \e AndroidManifest.xml: - \list - \li \uicontrol{Minimum required SDK} is set to API 9 or later. - - \note Qt Quick Controls with native \l{Android Style}{Android style} - require API 11 (Android v3.0) or later. - - \li Add \uicontrol{Application name} and \uicontrol{Application icon}. - - \li \uicontrol Permissions list has all the required permissions. - - \li \uicontrol Features list has the software or hardware features that your - application depends on. For example, NFC. - \endlist - - \note Qt adds the default permissions and features based on the module - dependencies of your application. If you do not want these default permissions - and features, remove the \c{<!-- %%INSERT_PERMISSIONS -->} and - \c{<!-- %%INSERT_FEATURES -->} comments from \e AndroidManifest.xml. For - information on the manifest XML format, see \l{Android: App Manifest}. - - \li Set up a \uicontrol keystore to sign the \e .apk. You can create a new - keystore if you do not have one. For more details, see - \l{Android APK}{QtCreator: Specifying Settings for Packages}. - - \li Select \uicontrol{Open package location after build} and run your - application to build the \e .apk. Qt Creator builds the \e .apk and opens the - folder containing the \e .apk. - - \li Log in to the \l{Google Play Developer Console} and upload the \e .apk - file, few screen captures of the application, and a description. -\endlist - -Now your application is available to other Android device users via -Google Play. You can also choose to publish the application to a smaller -group, so that you can test and improve the application before publishing it to -a larger audience. - -See \l{Deploying an Application on Android} for more information about how the -packaging is done and how you can influence it. -*/ - - -/*! -\page android-services.html -\title Android Services -\brief Provides information about Android Services support in Qt. - -Starting with Qt 5.7, you can create Android services using Qt. A service -is a component that runs in background, so, it has no user interface. It is -useful to perform long-term operations such as logging GPS, waiting for social -media notifications, and so on. A service will continue to run even if the -application that started it exits. - -To create a service, do the following steps: -\list 1 - \li Uncomment the service part of your \c AndroidManifest.xml. - - \li Make sure the \c service tag contains an \c android:process=":some_name" - attribute. It is needed to force the \c service to run in a separate - process than the \c activity. - - \li If you're using the same application (.so file) for activity and also - for service, you need to use \c android.app.arguments \c meta-data to - pass some arguments to your \c main function in order to know which one - is which. - - \li To enable background running, uncomment \c android.app.background_running - \c meta-data and set it to true (\c android:value="true" ). - -\endlist - -Qt loads the \c .so file defined in \c android.app.lib_name \c meta-data, -and calls the \c main function with all the arguments set in -\c android.app.arguments \c meta-data. - -See \l{http://developer.android.com/guide/components/services.html}{Android Services} -documentation for more information. -*/ diff --git a/doc/src/platforms/android/android-3rdparty-libs.qdoc b/doc/src/platforms/android/android-3rdparty-libs.qdoc new file mode 100644 index 000000000..afc085941 --- /dev/null +++ b/doc/src/platforms/android/android-3rdparty-libs.qdoc @@ -0,0 +1,88 @@ +/**************************************************************************** +** +** Copyright (C) 2020 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page android-3rdparty-libs.html + \title Third-party Android Libraries + \brief Provides instructions to include third-party Android libraries in an application. + + This guide describes how to include a Java-based third-party library in your application package. + There are many Java libraries which provide APIs that may be useful to your application. + One example is the \c{Google Play Services} add-on provided in the Android SDK. We will use this library + as an example in this guide, but the same approach may be taken to include other libraries, provided + that they have been made to be included as library projects in an Android application. + + \section1 Prerequisites + + This guide assumes that the \l{androiddeployqt} tool is used for constructing the deployment package. + When using Qt Creator for building and deploying, androiddeployqt is used behind the scenes, so this also + applies to development with Qt Creator. Explaining how to access the Java APIs after they have been + included in the application is not in the scope of this guide. + + \section1 Including the Library in the Source + + The very first thing we need to do is to copy the actual library project into the source of our + project. We want the contents of the library project to be copied without modifications into the + packaging directory, so we need to place it into the \c{Android Package Source Directory}. This + can be any directory which is pointed to by the \l{qmake} variable \c{ANDROID_PACKAGE_SOURCE_DIR}. + + If you are using Qt Creator, you can quickly set up the directory structure by clicking on the + \gui{Create AndroidManifest.xml} button in the \gui{Deployment} settings of your project. This + will create an \c{Android Package Source Directory} and place the \c{AndroidManifest.xml} file + inside it. Copy the library project directory into this directory. + + For example, once it has been installed via the \c{Android SDK Maintenance} application, + the \c{Google Play Services} library project is located under the path + \c{$ANDROID_SDK_ROOT/extras/google/google_play_services/libproject/google-play-services_lib}. If + the \c{Android Package Source Directory} of our project is \c{$PROJECT_ROOT/android}, then we + can copy the \c{google-play-services_lib} directory in there, creating + \c{$PROJECT_ROOT/android/google-play-services_lib}. + + \section1 Adding the Library to the Project Dependencies + + Once the library code has been copied into the project, we need to tell the Android build system + about it. This is done in the \c{project.properties} file. Create a file called \c{project.properties} + inside the \c{Android Package Source Directory} and add a line to it which assigns the relative + path of the library project to the property \c{android.library.reference.1}. If you want to include + multiple library projects, increment the counter at the end of the property name for each. + + In our example, we would create \c{$PROJECT_ROOT/android/project.properties} and add the + following contents: + + \badcode + android.library.reference.1=google-play-services_lib/ + \endcode + + \section1 Deployment + + And that's it: Provided that the path referenced in the \c{project.properties} file is located + under the \c{Android Package Source Directory}, the deployment tool will copy it into the + packaging directory and perform the necessary steps to include it in your \c{APK} or \c{AAB}. + You can now add Java code to your application which accesses the APIs provided by the library + project. + +*/ diff --git a/doc/src/platforms/android-building.qdoc b/doc/src/platforms/android/android-building.qdoc index 3180dbc2d..3180dbc2d 100644 --- a/doc/src/platforms/android-building.qdoc +++ b/doc/src/platforms/android/android-building.qdoc diff --git a/doc/src/platforms/android/android-deploying-application.qdoc b/doc/src/platforms/android/android-deploying-application.qdoc new file mode 100644 index 000000000..3503bc846 --- /dev/null +++ b/doc/src/platforms/android/android-deploying-application.qdoc @@ -0,0 +1,342 @@ +/**************************************************************************** +** +** Copyright (C) 2016 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \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}. +*/ diff --git a/doc/src/platforms/android/android-openssl-support.qdoc b/doc/src/platforms/android/android-openssl-support.qdoc new file mode 100644 index 000000000..249c04f6f --- /dev/null +++ b/doc/src/platforms/android/android-openssl-support.qdoc @@ -0,0 +1,92 @@ +/**************************************************************************** +** +** Copyright (C) 2020 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page android-openssl-support.html +\title Adding OpenSSL Support for Android +\brief Provides instructions to package OpenSSL libraries with your Qt application for Android. + +The Qt installation package comes with OpenSSL support but the OpenSSL libraries +are not part of the package due to legal restrictions in some countries. If your +application depends on OpenSSL, consider packaging the SSL libraries with your +Application Package (APK) as the target device may or may not have them. You +can use the \l{QSslSocket::supportsSsl()} static function to check for SSL +support on the target. + +The following instructions guide you to build and add the OpenSSL libraries to +the APK: +\list 1 + \li Download the latest OpenSSL 1.1.x sources from \l{http://www.openssl.org/source}. + + \li Extract the sources to a folder and navigate to that folder using + the CLI. + \note If your development platform is Windows, you need \c msys with + \c perl v5.14 or later to build OpenSSL. + + \li Add android llvm toolchain to your path: + \badcode + export PATH="<android_ndk_path>/toolchains/llvm/prebuilt/<host>/bin":$PATH + \endcode + + \li Configure the OpenSSL sources to build for Android using + the following command: + + \badcode + ./Configure shared android-<arch> -D__ANDROID_API__=21 + \endcode + + \note You must consider enabling/disabling the SSL features based on the + legal restrictions in the region where your application is available. + See the \l{OpenSSL Configure Options}{SSL configure options} for details about + the configurable features. + + \li Run \c{make SHLIB_VERSION_NUMBER= SHLIB_EXT=_1_1.so build_libs} to + build \c libcrypto and \c libssl shared libraries that are not versioned, + but with a \e _1_1 suffix. If you want to use a different suffix, then you must + set the \c ANDROID_OPENSSL_SUFFIX environment variable before you access the + Qt Network API. Without a suffix, Android 5 (API 21) will load the system + libraries \e libcrypto.so and \e libssl.so, which are OpenSSL 1.0, rather than + your libraries. + + \note Android does not load versioned libraries. + + \li Open your Qt project using Qt Creator and update the "Build Android APK" + settings to add \e libcrypto and \e libssl as additional libraries for + your project. + + \li Run your application to see it running on the device. +\endlist + +\note here \l{https://github.com/KDAB/android_openssl} you can find a script which +can be used to compile openssl for all android abis and also latest prebuilt libs. + +Qt Creator builds your application and creates an application package (APK) +with the OpenSSL libraries bundled in it. Once the APK is ready, it uses \c adb +to deploy the APK on the target you chose and launch the application. + +*/ + diff --git a/doc/src/platforms/android-platform-notes.qdoc b/doc/src/platforms/android/android-platform-notes.qdoc index 32fab8e97..32fab8e97 100644 --- a/doc/src/platforms/android-platform-notes.qdoc +++ b/doc/src/platforms/android/android-platform-notes.qdoc diff --git a/doc/src/platforms/android/android-publishing-to-googleplay.qdoc b/doc/src/platforms/android/android-publishing-to-googleplay.qdoc new file mode 100644 index 000000000..ff1bdf078 --- /dev/null +++ b/doc/src/platforms/android/android-publishing-to-googleplay.qdoc @@ -0,0 +1,94 @@ +/**************************************************************************** +** +** Copyright (C) 2020 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page android-publishing-to-googleplay.html +\title Publishing to Google Play +\brief Provides instructions to prepare your application for publishing. + +\l{Qt for Android} provides a complete solution to develop, build, and package +your applications for Android. Most of these tasks, especially packaging and +deployment are handled by Qt Creator providing rich developer experience. + +Every time you run the application using Qt Creator, an Android Application +Package (APK) is created and deployed onto the target (device or emulator) you +choose. With some minor changes to how the \e .apk is created, you can publish +your application on Google Play and monetize. The following +step-by-step instructions guide you to create an \e{.apk} that can go live +on Google Play: +\list 1 + \li Open your application project using Qt Creator v3.0 or later and change + its \uicontrol Build settings to build release version. + + \li Select \uicontrol {Create Templates} under \uicontrol Build settings to + create the template files such as \e AndroidManifest.xml and other + resources. + + \note You can edit the \e AndroidManifest.xml in \uicontrol General or + \uicontrol {XML Source} mode. + + \li Check for the following in \e AndroidManifest.xml: + \list + \li \uicontrol{Minimum required SDK} is set to API 9 or later. + + \note Qt Quick Controls with the \l{Material Style}{Material Style} + require API 11 (Android v3.0) or later. + + \li Add \uicontrol{Application name} and \uicontrol{Application icon}. + + \li \uicontrol Permissions list has all the required permissions. + + \li \uicontrol Features list has the software or hardware features that your + application depends on. For example, NFC. + \endlist + + \note Qt adds the default permissions and features based on the module + dependencies of your application. If you do not want these default permissions + and features, remove the \c{<!-- %%INSERT_PERMISSIONS -->} and + \c{<!-- %%INSERT_FEATURES -->} comments from \e AndroidManifest.xml. For + information on the manifest XML format, see \l{Android: App Manifest}. + + \li Set up a \uicontrol keystore to sign the \e .apk. You can create a new + keystore if you do not have one. For more details, see + \l{Android APK}{QtCreator: Specifying Settings for Packages}. + + \li Select \uicontrol{Open package location after build} and run your + application to build the \e .apk. Qt Creator builds the \e .apk and opens the + folder containing the \e .apk. + + \li Log in to the \l{Google Play Developer Console} and upload the \e .apk + file, few screen captures of the application, and a description. +\endlist + +Now your application is available to other Android device users via +Google Play. You can also choose to publish the application to a smaller +group, so that you can test and improve the application before publishing it to +a larger audience. + +See \l{Deploying an Application on Android} for more information about how the +packaging is done and how you can influence it. +*/ diff --git a/doc/src/platforms/android/android-services.qdoc b/doc/src/platforms/android/android-services.qdoc new file mode 100644 index 000000000..dbc008bad --- /dev/null +++ b/doc/src/platforms/android/android-services.qdoc @@ -0,0 +1,64 @@ +/**************************************************************************** +** +** Copyright (C) 2020 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page android-services.html +\title Android Services +\brief Provides information about Android Services support in Qt. + +Starting with Qt 5.7, you can create Android services using Qt. A service +is a component that runs in background, so, it has no user interface. It is +useful to perform long-term operations such as logging GPS, waiting for social +media notifications, and so on. A service will continue to run even if the +application that started it exits. + +To create a service, do the following steps: +\list 1 + \li Uncomment the service part of your \c AndroidManifest.xml. + + \li Make sure the \c service tag contains an \c android:process=":some_name" + attribute. It is needed to force the \c service to run in a separate + process than the \c activity. + + \li If you're using the same application (.so file) for activity and also + for service, you need to use \c android.app.arguments \c meta-data to + pass some arguments to your \c main function in order to know which one + is which. + + \li To enable background running, uncomment \c android.app.background_running + \c meta-data and set it to true (\c android:value="true" ). + +\endlist + +Qt loads the \c .so file defined in \c android.app.lib_name \c meta-data, +and calls the \c main function with all the arguments set in +\c android.app.arguments \c meta-data. + +See \l{http://developer.android.com/guide/components/services.html}{Android Services} +documentation for more information. +*/ + diff --git a/doc/src/platforms/android/android.qdoc b/doc/src/platforms/android/android.qdoc new file mode 100644 index 000000000..050c98efe --- /dev/null +++ b/doc/src/platforms/android/android.qdoc @@ -0,0 +1,205 @@ +/**************************************************************************** +** +** Copyright (C) 2019 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page android.html +\title Qt for Android +\brief Provides information about Android support in Qt. +\ingroup supportedplatform + +Qt for Android enables you to run Qt 5 applications on Android devices. +All Qt modules (essential and add-on) are supported except Qt \WebEngine, +Qt Serial Port, and the platform-specific ones (Qt Mac Extras, +Qt Windows Extras, and Qt X11 Extras). + +The following configurations are supported: + +\include supported-platforms.qdocinc android + +\br +The following list summarizes what you can do with Qt for Android: + +\list + \li Run \l{Qt Widgets}{Widget} and + \l{QML Applications}{QML} applications on the device + or emulator. + \li Support for native \l{Android Style}{Android style} with + Qt Quick Controls. + \li Handle \l{Qt Multimedia}{Multimedia} content in your Qt Quick 2 + applications. + \li Get \l{Qt Sensors}{sensor} readings and react to the changes. + \li Retrieve current position data using satellite and network + information. + \li Connect and exchange data with \l{Qt Bluetooth}{Bluetooth} + and \l{Qt NFC}{NFC}-enabled devices. + \li Integrate Java code into your application using + \l{Qt Android Extras}. + \li Develop secure applications using OpenSSL library. + \li Create \l{Android Services} + \li Create and deploy Application Package using Qt Creator. +\endlist + +The following topics provide more details about how to use Qt for Android: +\list + \li \l{Getting Started with Qt for Android}{Getting Started} + \li \l{Qt for Android - Building from Source} + \li \l{Porting to Android}{Porting a Qt Application} + \li \l{Qt for Android Examples}{Examples} + \li \l{Adding OpenSSL Support for Android} + \li \l{Android Services}{Creating Android Services} + \li \l{Third-party Android Libraries}{Including third-party Android libraries in an application} + \li \l{Qt Creator: Deploying Applications to Android Devices}{Deploying to the Device} + \li \l{Publishing to Google Play} + \li \l{Platform and Compiler Notes - Android}{Platform Notes} + \li \l{Android GNU C++ run-time licensing} +\endlist +*/ + +/*! +\page android-getting-started.html +\title Getting Started with Qt for Android +\brief Provides instructions to install and configure your development environment. + +\section1 Installing the Prerequisites + +In order to use \l{Qt for Android}, you need the following: + +\list +\li \l{http://developer.android.com/sdk/index.html}{The Android SDK Tools} + \note If your Qt version is earlier than v5.9, use the SDK tools package + v25.2.5 or earlier. +\li \l{http://developer.android.com/tools/sdk/ndk/index.html}{The Android NDK} + \list + \li Qt 5.11 and below + \list + \li NDK r10e + \li GCC toolchain + \endlist + \li Qt 5.12.0 to 5.12.5 + and Qt 5.13.0 to 5.13.1 + \list + \li NDK r19c + \li \e android-clang + \endlist + \li Qt 5.14+, Qt 5.13.2+ + and Qt 5.12.6+ + \list + \li NDK r20b or r21 + \li \e android-clang + \li \note Qt 5.14.0 and 5.14.1 with NDK r21 have a bug fixed at \l{https://bugreports.qt.io/browse/QTBUG-81461}{QTBUG-81461}. + \endlist + \endlist + +\li \l{http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html}{Java SE Development Kit} (JDK) v6 or later. You can also use \l{http://openjdk.java.net}{OpenJDK} on Linux. +\endlist + +After installing these tools, update the Android SDK by installing the API +and build tools packages required for development. You can install these packages +either through Android Studio or using the command line tools package you installed +earlier. For more details, refer to the +\l{https://developer.android.com/studio/intro/update.html}{Android Studio} +documentation. + +\note Make sure to unpack the Android SDK and NDK to a writeable location that Qt Creator +can access later. Otherwise, Qt Creator won't be able to use \c sdkmanager or find all +components even if they were installed manually. + +\section2 Updating the Android SDK + +The command line tools provided by the Android SDK Tools package also enables updating +the SDK, but without a GUI. For example, the following command on Ubuntu updates the SDK +by installing the latest \c build-tools, \c platform-tools, \c emulator, and \c patcher +packages: + +\badcode +./bin/sdkmanager --update +\endcode + +To install a specific package, use \c sdkmanager from +\c{<ANDROID_SDK_ROOT>/tools/bin}. For example, the following command installs the +\c android-10 platforms package on Ubuntu: + +\badcode +./sdkmanager "platforms;android-10" +\endcode + +For more details, refer to the +\l{https://developer.android.com/studio/command-line/sdkmanager.html}{sdkmanager} +documentation. + +\section1 Configuring Your Development Host + +\section2 Windows + +The default USB driver on Windows does not allow debugging using +Android Debug Bridge (ADB) tool. You must install the additional USB driver +provided by the \e extras Android SDK package. Use the following command from +the Windows command prompt to install the extras package: + +\badcode +sdkmanager.bat "extras;google;usb_driver" +\endcode + +After the package installation is complete, install the driver from +\c{<ANDROID_SDK_ROOT>/extras/google/usb_driver}. Try running a few basic +\l{http://developer.android.com/tools/help/adb.html}{adb} commands now +and check whether your Android device responds to it. + +\section2 64-bit Linux + +If you're developing on a 64-bit Linux machine, you must install the +following dependencies in order to run 32-bit executables like \c adb, which +allows Qt Creator to find devices to deploy to: + +\badcode +sudo apt-get install libstdc++6:i386 libgcc1:i386 zlib1g:i386 libncurses5:i386 +\endcode + +To run the emulator, the following dependencies are also necessary: + +\code +sudo apt-get install libsdl1.2debian:i386 +\endcode + +\section2 Qt Creator IDE + +The Qt Creator IDE that came with the Qt 5 installation on your development +host, must be configured to enable developing applications for Android. Launch +Qt Creator and select \uicontrol Tools > \uicontrol Options > +\uicontrol Devices > \uicontrol Android to add the Android NDK and SDK paths. +For more details, refer to \l{Qt Creator: Connecting Android Devices}{Qt Creator Manual}. + +\section1 Testing Your Setup + +Now you can test your development setup by running the examples that came +with the Qt 5 installation. You can browse these examples in +Qt Creator \uicontrol Welcome mode. Use the \c android filter in the search +field to list all the examples tested on Android. + +To develop a simple application from scratch, see \l{Creating a Mobile Application}. +*/ + diff --git a/doc/src/examples-android.qdoc b/doc/src/platforms/android/examples-android.qdoc index 4faa63a00..4faa63a00 100644 --- a/doc/src/examples-android.qdoc +++ b/doc/src/platforms/android/examples-android.qdoc diff --git a/doc/src/platforms/android/porting-to-android.qdoc b/doc/src/platforms/android/porting-to-android.qdoc new file mode 100644 index 000000000..27149b861 --- /dev/null +++ b/doc/src/platforms/android/porting-to-android.qdoc @@ -0,0 +1,88 @@ +/**************************************************************************** +** +** Copyright (C) 2020 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page porting-to-android.html +\title Porting to Android +\brief Provides instructions to port your existing Qt application to Android. + +In this section, we are going to port an existing Qt Application to +\l{Qt for Android}{Android} and deploy it to the device. + +Most Qt applications should be portable to Android with ease, unless they +depend on a specific hardware or software feature not supported by Android. +If your application is not using any such feature, deployment is probably the +only step that demands some changes to your application. + +\include porting-notes.qdocinc using resources + +The other approach is to deploy the resources into the package's \c{assets} +directory. It is the best option if you want to achieve better +interoperability with the Android APIs. You can access all resources in the +directory using the "assets:" prefix. Unlike qrc, this approach is not a +cross-platform solution. + +The following step-by-step instructions guide you to port an existing Qt Quick +application to Android using the qrc approach: + +\list 1 + \li Open the existing project in Qt Creator and configure it + with "Android for ARM" kit. For more information, see + \l{Qt Creator: Configuring Projects} + \li Identify all the resources used by your application and add them to one + or more qrc files. + Qt Creator updates your qmake project file with the "RESOURCES" + variable listing the qrc files you added. + \li To load or refer to the resources in the qrc file from your C++ code, + use the "qrc:" scheme followed by the absolute URL. For example, to + load the \c{main.qml} file from \c{resources.qrc}, you can use the + following C++ code: + + \code + QQuickView viewer; + viewer.setSource(QUrl("qrc:/qml/main.qml")); + viewer.show(); + \endcode + + \note QML documents can refer to the contents in qrc files using the + relative path to the document. Such references do not require the + "\c{qrc:}" or "\c{:/}" prefix. + \li Save the changes to your project and run the application. +\endlist + +\note Qt Quick Controls in the application will use native +\l{Android Style}{Android style} if the target device is running +Android 3.0 (API 11) or later. The application should function normally on +devices with Android versions earlier than v3.0, but without native style for +controls. + +Qt Creator deploys your application on the Android device, if the +device is detected by the PC. Otherwise, it tries to run the application on an +AVD (Android Virtual Device). You will be prompted to create one if there are no +AVDs found. +*/ + |