androiddev.qdoc 10.4 KB
Newer Older
1
/****************************************************************************
Leena Miettinen's avatar
Leena Miettinen committed
2
**
3 4
** Copyright (C) 2016 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
Leena Miettinen's avatar
Leena Miettinen committed
5
**
6
** This file is part of the Qt Creator documentation.
Leena Miettinen's avatar
Leena Miettinen committed
7
**
8 9 10 11 12 13 14
** 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.
Leena Miettinen's avatar
Leena Miettinen committed
15
**
16
** GNU Free Documentation License Usage
Leena Miettinen's avatar
Leena Miettinen committed
17 18
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
19 20 21 22
** 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.
Leena Miettinen's avatar
Leena Miettinen committed
23
**
24
****************************************************************************/
Leena Miettinen's avatar
Leena Miettinen committed
25 26 27

    /*!

28
    \contentspage {Qt Creator Manual}
29
    \previouspage creator-connecting-mobile.html
Leena Miettinen's avatar
Leena Miettinen committed
30
    \page creator-developing-android.html
31
    \nextpage creator-developing-baremetal.html
Leena Miettinen's avatar
Leena Miettinen committed
32 33 34 35 36 37 38

    \title Connecting Android Devices

    You can connect Android devices to the development PC to build, run, debug,
    and analyze applications on them from \QC.

    If you have a tool chain for building applications for Android devices
39 40 41
    installed on the development PC, you can add it to \QC. You can then add a
    \l{glossary-buildandrun-kit}{kit}
    with the Android device type, the tool chain, and the Qt version for Android,
42 43
    to build and run applications on Android devices. You can also allow \QC to
    automatically configure the kit.
Leena Miettinen's avatar
Leena Miettinen committed
44

45 46 47 48 49 50
    The Android Debug Bridge (adb) command line tool is integrated to \QC to
    enable you to deploy applications to connected Android devices, to run
    the applications on them, and to read logs from them. It includes a client
    and server that run on the development host and a daemon that runs on the
    emulator or device.

Leena Miettinen's avatar
Leena Miettinen committed
51 52 53 54 55 56
    \section1 Requirements

    To use \QC to develop Qt applications for Android, you need the following:

    \list

57 58
        \li \l{http://www.oracle.com/technetwork/java/javase/downloads/index.html}
            {Java SE Development Kit (JDK)} version 6, or later
59

60 61 62 63 64 65 66 67 68 69
        \li A build tool for building application packages for Android devices:

            \list

                \li \l{http://ant.apache.org/bindownload.cgi}{Apache Ant} 1.8.0,
                    or later

                \li \l{http://www.gradle.org}{Gradle}

            \endlist
Leena Miettinen's avatar
Leena Miettinen committed
70

71 72
        \li A tool chain for building applications for Android devices provided
            by the
73 74
            \l{http://developer.android.com/sdk/index.html}{Android SDK} and
            \l{http://developer.android.com/tools/sdk/ndk/index.html}
75
            {Android NDK} from Google.
Leena Miettinen's avatar
Leena Miettinen committed
76

77 78
            \note Android Studio is currently not supported by \QC.

79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108
        \li On Windows, you also need the following:

          \list

            \li MinGW v4.8.0 revision 2

            \li Android Debug Bridge (ADB) driver on the Windows platform to
                enable USB debugging. The default USB driver on Windows does not
                allow debugging. For more information about obtaining the USB
                driver, see \l{http://developer.android.com/sdk/win-usb.html}.

                After installing the driver, try running a few basic
                \l{http://developer.android.com/tools/help/adb.html}{adb}
                commands to check that your device responds to them.

          \endlist

        \endlist

        After installing these tools, update the Android SDK to get the API
        and tools packages required for development. You can use the
        \l{http://developer.android.com/tools/help/android.html}{android} tool
        that comes with the SDK Tools package. For example, on Ubuntu the
        following command starts the
        \l{http://developer.android.com/sdk/installing/adding-packages.html}
        {Android SDK Manager}, where you can select the packages to install:

        \code
        ./android update sdk
        \endcode
Leena Miettinen's avatar
Leena Miettinen committed
109

110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127
    \section1 Selecting the APK Build Tool

    On Android, applications are distributed in specially structured type of ZIP
    packages called APK. You can use either Ant or Gradle to build APKs. Using
    Gradle has the following benefits:

    \list

        \li It is 25 to 50 percent faster than Ant when rebuilding packages.

        \li It is integrated with Android Studio.

        \li It supports easily adding Android Extras libraries, such as
            Google Play services or Android extension files (.obb) to your
            project.

    \endlist

128
    \section1 Setting Up the Development Environment
Leena Miettinen's avatar
Leena Miettinen committed
129

130 131 132 133 134
    You must download and install the latest Android NDK and SDK, and update the
    SDK to get the API and tools packages needed for development. In addition,
    you must install Qt for Android as part of Qt 5.2, or later.

    For more information, see \l{Qt for Android}.
Leena Miettinen's avatar
Leena Miettinen committed
135 136 137 138 139

    To configure connections between \QC and Android devices:

    \list 1

140
        \li Select \uicontrol Tools > \uicontrol Options > \uicontrol Android to add paths to the
141
            Android NDK and SDK.
Leena Miettinen's avatar
Leena Miettinen committed
142

143
            You can use the \inlineimage download.png
144
            (\uicontrol Download) buttons to go to the sites where you can download
145 146
            the Android NDK and SDK.

147
            \image qtcreator-options-android1.png "Android options"
Leena Miettinen's avatar
Leena Miettinen committed
148

149
        \li Select the \uicontrol {Automatically create kits for Android tool chains}
150 151
            check box to allow \QC to create the kits for you. \QC displays a
            warning if it cannot find a suitable Qt version.
Leena Miettinen's avatar
Leena Miettinen committed
152

153 154 155 156
        \li Select the tool to use for building application packages:

            \list

157
                \li To use Gradle, select the \uicontrol {Use Gradle instead of Ant}
158 159 160
                    check box.

                \li To use Ant, add the path to the Ant executable in the
161
                    \uicontrol {Ant executable} field.
162 163 164

            \endlist

165 166
        \li Select \uicontrol File > \uicontrol {New File or Project} > \uicontrol Application >
            \uicontrol {Qt Quick Application} > \uicontrol Choose, and
167 168
            follow the instructions of the wizard. For more information, see
            \l{Creating Qt Quick Projects}.
Leena Miettinen's avatar
Leena Miettinen committed
169

170
        \li To specify settings for deploying applications to Android, select
171 172
            \uicontrol Projects > \uicontrol Run for the \uicontrol Android kit, and then select
            \uicontrol Details to view the \uicontrol {Deploy configurations}. For more
Leena Miettinen's avatar
Leena Miettinen committed
173 174 175
            information about the options you have, see
            \l{Deploying Applications to Android Devices}.

176
        \li Enable debugging on your Android device.
Leena Miettinen's avatar
Leena Miettinen committed
177

178
            Debugging is enabled in different ways on different Android devices.
179 180 181 182
            Look for \uicontrol {USB Debugging} under \uicontrol {Developer Options}. On
            some devices \uicontrol {Developer Options} is hidden and becomes visible
            when you tap the \uicontrol {Build number} field in \uicontrol Settings >
            \uicontrol About several times.
183

184 185
        \li Connect the Android device to the development PC with a USB cable.
            You might be asked to select a device in the
186
            \uicontrol {Select Android Devices} dialog.
187
    \endlist
188

189 190 191
    \section1 Selecting Android Devices

    When you deploy an application to an Android device with Android
192
    version 4.2 or later, the \uicontrol {Select Android Devices} dialog opens. It
193
    lists the devices that are connected to the development PC. and their
194
    status. You can select devices from the \uicontrol {Compatible Devices} list for
195 196 197
    deployment.

    If \QC determines that a device is not ready for deployment, it places the
198
    device in the \uicontrol {Incompatible Devices} list, with information about the
199 200
    issue. For example, you might need to authorize the connection on the
    device. After you authorize the connection on the device, select
201 202
    \uicontrol {Refresh Device List}. The device is moved to the
    \uicontrol {Compatible Devices} list and you can select it for deployment.
203

204
    Other reasons for placing a device on the \uicontrol {Incompatible Devices} are
205 206 207 208 209 210 211
    that the Android version on the device is too old or that the tool chain
    used for building does not match the Android architecture on the device
    (for example, you cannot deploy an ARM build on an x86 device).

    \image qtcreator-android-select-devices.png "Select Android Devices dialog"

    Android Virtual Devices (AVD) are also listed. To create new AVDs, select
212
    \uicontrol {Create Android Virtual Device}.
213 214

    To set a device as the default device for a particular Android architecture,
215 216
    select the \uicontrol {Always use this device for architecture} check box. The
    \uicontrol {Select Android Devices} dialog will not appear until you switch to
217 218
    another project or restart \QC.

219 220 221
    \section1 Using the Android Emulator

    To run your application on the Android Emulator, you must create Android
222 223
    virtual devices (AVD). Select \uicontrol Tools > \uicontrol Options > \uicontrol Android >
    \uicontrol Add. If you run an application without a device connected to the
224 225
    development PC and without an AVD specified, \QC asks you to add an AVD.

226
    To manage AVDs, select \uicontrol {Start AVD Manager}.
227 228 229 230 231

    \note The Android Emulator has a bug that prevents it from starting on some
    systems. If the Android Emulator does not start, you can try starting it
    manually by running the \c {emulator-arm} command from the command line.

Leena Miettinen's avatar
Leena Miettinen committed
232 233 234 235 236 237 238
    \section1 Debugging on Android Devices

    Android devices support debugging multi-thread applications in version
    2.2.1 and later. If you use AVD, select Android 2.3, or later. For more
    information, see the Android documentation.

    In addition, debugging is supported at android-10 API level, or higher. In
239
    the run settings for the project, in the \uicontrol {Android build SDK} field,
Leena Miettinen's avatar
Leena Miettinen committed
240 241 242 243 244 245 246 247 248
    select android-10, or higher. For more information about Android API levels,
    see \l{http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels}
    {What is API Level?}.

    \note Select a \l{glossary-build-config}{debug build configuration} to build
    the application for debugging.

*/