qtdoc/doc/src/platforms/android/android.qdoc

/****************************************************************************
**
** 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}.
*/