Android: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
(Add more explanation to possible values for Android-related configure arguments.)
(Add a note to a bug on Qt 5.14 with NDK r21.)
(9 intermediate revisions by 6 users not shown)
Line 1: Line 1:
[[Category:HowTo]]
[[Category:HowTo]]
[[Category:Qt for Android]]
[[Category:Qt for Android]]
These are build instructions for building Qt for Android on Linux or Mac OS X. For cross-compiling on Windows, this is currently [[Building qt-android on windows| possible under cmd.exe]].
These are building instructions for building Qt for Android on Linux or Mac OS X. For cross-compiling on Windows, this is currently [[Building qt-android on windows|possible under cmd.exe]].


For general information about Qt 5 for Android, please visit the [[Qt5ForAndroid| wiki]] for that.
For general information about Qt 5 for Android, please visit the [[Qt5ForAndroid|wiki]] for that.


N.B.
N.B.


* When using GCC toolchains on Windows (MinGW, Android NDK, etc.) take into account that there is a restrictions on a build path prefix length [https://bugreports.qt.io/browse/QTBUG-52242 QTBUG-52242].
* When using GCC toolchains on Windows (MinGW, Android NDK, etc.) take into account that there are restrictions on a build path prefix length [https://bugreports.qt.io/browse/QTBUG-52242 QTBUG-52242].
* When using MSys shell you should not pass Unix-like paths in <tt>-prefix</tt> argument [https://bugreports.qt.io/browse/QTBUG-52675 QTBUG-52675]
* When using MSys shell you should not pass Unix-like paths in <tt>-prefix</tt> argument [https://bugreports.qt.io/browse/QTBUG-52675 QTBUG-52675]


= Building Qt 5 for Android =
= Building Qt 5 for Android =


These are the current build instructions to get to the point where you can deploy a Qt app to an Android device using Qt Creator.
The following sections will help you configure the Android SDK and NDK, deploy an x86 Android emulator and configure the emulator and SDK for use with Qt Creator.


# First of all you need an Android SDK.
== Installing the Android SDK and NDK ==
#* The SDK is bundled with Android Studio: https://developer.android.com/studio/index.html
 
=== Scripted installation for Linux ===
The following packages (alternatives may be supported) for Debian-based Linux are required:
apt install build-essential default-jre openjdk-8-jdk-headless android-sdk android-sdk-platform-23 libc6-i386
The following bash script will download the SDK and NDK version r19c. Run the script from the directory you wish to install to, such as /home/username/android_tools
 
'''Important:''' Run the script as the user that will be using it later (do not sudo)<syntaxhighlight lang="bash">
#!/bin/bash
 
ndkVersion="r19c"
sdkBuildToolsVersion="28.0.3"
sdkApiLevel="android-28"
toolsVersion="r26.1.1"
 
repository=https://dl.google.com/android/repository
toolsFile=sdk-tools-linux-4333796.zip
toolsFolder=android-sdk-tools
ndkFile=android-ndk-$ndkVersion-linux-x86_64.zip
ndkFolder=android-ndk-$ndkVersion
 
rm -rf $toolsFolder
rm -rf $ndkFolder
 
echo "Downloading SDK tools from $repository"
wget -q $repository/$toolsFile
unzip -qq $toolsFile -d $toolsFolder
 
echo "Downloading NDK from $repository"
wget -q $repository/$ndkFile
unzip -qq $ndkFile
 
rm $toolsFile
rm $ndkFile
 
echo "Configuring environment"
export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64
export PATH=$PATH:$JAVA_HOME/bin
 
# Optional workaround for issue with certain JDK/JRE versions
#cp $toolsFolder/tools/bin/sdkmanager $toolsFolder/tools/bin/sdkmanager.backup
#sed -i 's/^DEFAULT_JVM_OPTS.*/DEFAULT_JVM_OPTS='"'\"-Dcom.android.sdklib.toolsdir=\$APP_HOME\" -XX:+IgnoreUnrecognizedVMOptions --add-modules java.se.ee'"'/' \
#        $toolsFolder/tools/bin/sdkmanager
 
echo "Installing SDK packages"
cd $toolsFolder/tools/bin
echo "y" | ./sdkmanager "platforms;$sdkApiLevel" "platform-tools" "build-tools;$sdkBuildToolsVersion" >> sdkmanager.log
echo "y" | ./sdkmanager --install "emulator" >> sdkmanager.log
echo "y" | ./sdkmanager --install "system-images;android-21;google_apis;x86" >> sdkmanager.log
echo "no" | ./avdmanager create avd -n x86emulator -k "system-images;android-21;google_apis;x86" -c 2048M -f >> sdkmanager.log
 
echo "Provisioning complete. Here's the list of packages and avd devices:"
./sdkmanager --list
./avdmanager list avd
</syntaxhighlight>
 
=== Manual Installation ===
# If the Android SDK is not installed with the package manager and script above, it can be obtained as part of the official Android Studio release.
#* Download Android Studio: https://developer.android.com/studio/index.html
#* Open Android Studio and run the SDK Manager tool, which is found under [https://developer.android.com/studio/intro/update.html#sdk-manager Tools > Android > SDK Manager] (if you don't have the SDK Manager menu item in the Tools menu and the toolbar isn't visible, you can enable this from the View menu by checking Toolbar).
#* Open Android Studio and run the SDK Manager tool, which is found under [https://developer.android.com/studio/intro/update.html#sdk-manager Tools > Android > SDK Manager] (if you don't have the SDK Manager menu item in the Tools menu and the toolbar isn't visible, you can enable this from the View menu by checking Toolbar).
#* For Qt 5.6 or earlier: Install API levels 10, 11, 16 and 18 (you may need to check the "Obsolete" checkbox to see these in the SDK manager). Beginning with Qt 5.7, any API level >= 18 will work.
#* '''Important:''' For Qt 5.6 or earlier: Install API levels 10, 11, 16 and 18 (you may need to check the "Obsolete" checkbox to see these in the SDK manager). '''Beginning with Qt 5.7''', any API level >= 18 will work.
#** Android API level 11 is required to build QtMultimedia.
#** Android API level 11 is required to build QtMultimedia.
#** Android API level 18 is required to build QtBluetooth (from Qt 5.5 onwards).
#** Android API level 18 is required to build QtBluetooth (from Qt 5.5 onwards).
#** Android API level 10, 11 and 16 are required for QtBase.
#** Android API levels 10, 11 and 16 are required for QtBase.
#** Note that this is only necessary for building Qt itself. You can build Qt applications against any API level you wish, As long as it is equal to or higher than 13.
#** Note that this is only necessary for building Qt itself. You can build Qt applications against any API level you wish, As long as it is equal to or higher than 13.
# You also need an Android NDK: https://developer.android.com/tools/sdk/ndk/index.html
# You also need an Android NDK: https://developer.android.com/tools/sdk/ndk/index.html
#* '''Important:''' If you are building Qt with the gcc toolchain, you will need the Android NDK r10e. This is because NDK r11, r12 and r15 are known to have issues<ref name="known-issues">[[Qt for Android known issues| Known issues with the Qt for Android build]]</ref> with gcc. NDK r13 and r14 are also likely to have the same issues. r15 produces applications that fail with the error message 'This application failed to start because it could not find or load the Qt platform plugin "android"'. We recommend to use the android-clang toolchain for compiling, in which case the latest NDK release should be preferred.
#* '''Important:''' for Qt 5.12 downwards, GCC toolchains are used and Android NDK r10e is required.
# Install a 32 bit JDK whose version is at least 1.6. This can be found on Oracle's website. Alternatively, OpenJDK can be used on Linux.
#* '''Important:''' from Qt 5.12 onwards, the GCC toolchains are no longer supported in the Android NDK.
#* If you're on a 64 bit Ubuntu/Debian, you may also need to install a 32 bit runtime environment:
#* '''Important:''' For Qt 5.12.[0-5], and Qt 5.13.[0-1], Android NDK r19c is required.
#* '''Important:''' As of Qt 5.14, Qt 5.13.2+ and Qt 5.12.6+, the latest Android NDK (r20b or r21) is required. Qt 5.14.0 and 5.14.1 with NDK r21 might have a build issue that is solved at [https://bugreports.qt.io/browse/QTBUG-81461 QTBUG-81461].
#* '''Important:''' If you are building Qt with the GCC toolchain (pre-Qt 5.12 only), you will need the Android NDK r10e. This is because NDK r11, r12 and r15 are known to have issues<ref name="known-issues">[[Qt for Android known issues| Known issues with the Qt for Android build]]</ref> with GCC. NDK r13 and r14 are also likely to have the same issues. r15 produces applications that fail with the error message 'This application failed to start because it could not find or load the Qt platform plugin "android"'. We recommend using the android-clang toolchain for compiling, in which case the latest NDK release should be preferred.
#* You need to make sure that the NDK supports the API level you're targeting. You can do this by checking the path-to-NDK/platforms directory.
# Install a JDK whose version is at least 1.6. This can be found on Oracle's website. Alternatively, OpenJDK can be used on Linux. <pre>apt-get install openjdk-8-jdk</pre>
#* If you're on a 64 bit Ubuntu/Debian, you may also need to install a 32-bit runtime environment:
#*:<pre>apt-get install libc6-i386</pre>
#*:<pre>apt-get install libc6-i386</pre>
== Building Qt ==
# Get Qt Creator 2.7.2 (or later): http://qt.io/download#qt-creator
# Get Qt Creator 2.7.2 (or later): http://qt.io/download#qt-creator
# Get Qt 5:
# Get Qt 5:
Line 33: Line 97:
#:<pre>perl init-repository</pre>
#:<pre>perl init-repository</pre>
# Optionally checkout target Qt version to use.
# Optionally checkout target Qt version to use.
#:<pre>git checkout v5.9.3</pre>
#:<pre>git checkout v5.12.7</pre>
#:<pre>git submodule update --recursive</pre>
#:<pre>git submodule update --recursive</pre>
# Configure Environment Variables.
# Configure Environment Variables.
#* You need to set JAVA_HOME and add JAVA_HOME/bin to your PATH. On Linux, a good place to do this is at the end of ~/.profile:
#* You need to set JAVA_HOME and add JAVA_HOME/bin to your PATH. On Linux, a good place to do this is at the end of ~/.profile:
#:<pre>export JAVA_HOME=/usr/lib/jvm/java-6-openjdk-i386</pre>
#:<pre>export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64</pre>
#:<pre>export PATH=$PATH:$JAVA_HOME/bin</pre>
#:<pre>export PATH=$PATH:$JAVA_HOME/bin</pre>
# Configure Qt and skip unsupported modules:
# Configure Qt and skip unsupported modules:
#:<pre>./configure -xplatform android-clang --disable-rpath -nomake tests -nomake examples -android-ndk <path/to/ndk> -android-sdk <path/to/sdk> -android-ndk-host <e.g. linux-x86_64> -android-toolchain-version <e.g. 4.9> -skip qttranslations -skip qtserialport -no-warnings-are-errors</pre>''-android-toolchain-version'' can be any version listed in the toolchains directory of your NDK directory (-android-ndk). For example, arm-linux-androideabi-4.9 would be 4.9.
#:<pre>./configure -xplatform android-clang --disable-rpath -nomake tests -nomake examples -android-ndk <path/to/ndk> -android-sdk <path/to/sdk> -android-ndk-host <e.g. linux-x86_64> -skip qttranslations -skip qtserialport -no-warnings-are-errors</pre>
#:''-android-ndk-host'' will be windows-x86_64 if you're on 64-bit Windows, for example. For more values, check qtbase/configure.pri.
#:''-android-ndk-host'' will be windows-x86_64 if you're on 64-bit Windows, for example. For more values, check qtbase/configure.pri.
#:''-android-abis'' starting with Qt 5.14 we'd added multi-abi build and you can use this parameter to filer the ABIs you want to build. By default is ''armeabi-v7a, arm64-v8a, x86, x86_64''
#:'''Note:''' the highest API level that the r10e NDK supports is 21, so it may be necessary to install that and then pass the following in addition to the arguments listed above: <code>-android-ndk-platform android-21</code>
#:'''Note:''' the highest API level that the r10e NDK supports is 21, so it may be necessary to install that and then pass the following in addition to the arguments listed above: <code>-android-ndk-platform android-21</code>
# Build. Run the ''make'' command to build the configured Qt parts.  
# Build. Run the ''make'' command to build the configured Qt parts.  
#:<pre>make</pre>
#:<pre>make -j8</pre>
#Install. Run the ''make install'' command to install the built Qt parts. If you have not used the configure option ''--prefix <install-dir>'' the installation is done under the directory path ''/usr/local/Qt-<version>''.  Under Debian/Ubuntu you should prefix the make command with the ''sudo'' command.<pre>make install</pre>
#Install. Run the ''make install'' command to install the built Qt parts. If you have not used the configure option ''--prefix <install-dir>'' the installation is done under the directory path ''/usr/local/Qt-<version>''.  Under Debian/Ubuntu you should prefix the make command with the ''sudo'' command.<pre>make install</pre>
# Start the Qt Creator you built earlier.
 
# Go into Tools-> Options -> Devices -> Android and set the right paths to the Android SDK and NDK, etc. For example:
== Configuring Qt Creator ==
#*Android SDK Location: /home/johnsmith/dev/android-sdk-linux
# Start the Qt Creator you built or downloaded earlier.
#*Android NDK Location: /home/johnsmith/dev/android-ndk-r18
# Go into Tools -> Options -> Devices -> Android and set the right paths to Java, and the Android SDK and NDK, etc. For example:
#*JDK Location: /usr/lib/jvm/java-6-openjdk-i386
#*JDK Location: /usr/lib/jvm/java-8-openjdk-amd64
# Add your newly built Qt version to Options -> Build & Run -> Qt Versions.
#*Android SDK Location: /home/johnsmith/dev/android-sdk-tools
# At this point you should be able to create a project and configure it for the Android kit. In order to test, go into the Run settings for your project. Under Deploy Configuration, check the Use Qt libraries from local device option. Also select the Deploy local Qt libraries radio button.
#*Android NDK Location: /home/johnsmith/dev/android-ndk-r19c
# Add your newly built Qt version to Tools -> Options -> Kits -> Qt Versions.
# Add a new kit using that Qt version (or clone an existing pre-built Qt for Android kit and just change the Qt version) in Tools -> Options -> Kits -> Kits.
# At this point, you should be able to create a project and configure it for the Android kit. In order to test, go into the Run settings for your project. Under Deploy Configuration, check the Use Qt libraries from the local device option. Also, select the Deploy local Qt libraries radio button.


==References==
==References==
<references />
<references />

Revision as of 19:52, 11 February 2020

These are building instructions for building Qt for Android on Linux or Mac OS X. For cross-compiling on Windows, this is currently possible under cmd.exe.

For general information about Qt 5 for Android, please visit the wiki for that.

N.B.

  • When using GCC toolchains on Windows (MinGW, Android NDK, etc.) take into account that there are restrictions on a build path prefix length QTBUG-52242.
  • When using MSys shell you should not pass Unix-like paths in -prefix argument QTBUG-52675

Building Qt 5 for Android

The following sections will help you configure the Android SDK and NDK, deploy an x86 Android emulator and configure the emulator and SDK for use with Qt Creator.

Installing the Android SDK and NDK

Scripted installation for Linux

The following packages (alternatives may be supported) for Debian-based Linux are required:

apt install build-essential default-jre openjdk-8-jdk-headless android-sdk android-sdk-platform-23 libc6-i386

The following bash script will download the SDK and NDK version r19c. Run the script from the directory you wish to install to, such as /home/username/android_tools

Important: Run the script as the user that will be using it later (do not sudo)

#!/bin/bash

ndkVersion="r19c"
sdkBuildToolsVersion="28.0.3"
sdkApiLevel="android-28"
toolsVersion="r26.1.1"

repository=https://dl.google.com/android/repository
toolsFile=sdk-tools-linux-4333796.zip
toolsFolder=android-sdk-tools
ndkFile=android-ndk-$ndkVersion-linux-x86_64.zip
ndkFolder=android-ndk-$ndkVersion

rm -rf $toolsFolder
rm -rf $ndkFolder

echo "Downloading SDK tools from $repository"
wget -q $repository/$toolsFile
unzip -qq $toolsFile -d $toolsFolder

echo "Downloading NDK from $repository"
wget -q $repository/$ndkFile
unzip -qq $ndkFile

rm $toolsFile
rm $ndkFile

echo "Configuring environment"
export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64
export PATH=$PATH:$JAVA_HOME/bin

# Optional workaround for issue with certain JDK/JRE versions
#cp $toolsFolder/tools/bin/sdkmanager $toolsFolder/tools/bin/sdkmanager.backup
#sed -i 's/^DEFAULT_JVM_OPTS.*/DEFAULT_JVM_OPTS='"'\"-Dcom.android.sdklib.toolsdir=\$APP_HOME\" -XX:+IgnoreUnrecognizedVMOptions --add-modules java.se.ee'"'/' \
#        $toolsFolder/tools/bin/sdkmanager

echo "Installing SDK packages"
cd $toolsFolder/tools/bin
echo "y" | ./sdkmanager "platforms;$sdkApiLevel" "platform-tools" "build-tools;$sdkBuildToolsVersion" >> sdkmanager.log
echo "y" | ./sdkmanager --install "emulator" >> sdkmanager.log
echo "y" | ./sdkmanager --install "system-images;android-21;google_apis;x86" >> sdkmanager.log
echo "no" | ./avdmanager create avd -n x86emulator -k "system-images;android-21;google_apis;x86" -c 2048M -f >> sdkmanager.log

echo "Provisioning complete. Here's the list of packages and avd devices:"
./sdkmanager --list
./avdmanager list avd

Manual Installation

  1. If the Android SDK is not installed with the package manager and script above, it can be obtained as part of the official Android Studio release.
    • Download Android Studio: https://developer.android.com/studio/index.html
    • Open Android Studio and run the SDK Manager tool, which is found under Tools > Android > SDK Manager (if you don't have the SDK Manager menu item in the Tools menu and the toolbar isn't visible, you can enable this from the View menu by checking Toolbar).
    • Important: For Qt 5.6 or earlier: Install API levels 10, 11, 16 and 18 (you may need to check the "Obsolete" checkbox to see these in the SDK manager). Beginning with Qt 5.7, any API level >= 18 will work.
      • Android API level 11 is required to build QtMultimedia.
      • Android API level 18 is required to build QtBluetooth (from Qt 5.5 onwards).
      • Android API levels 10, 11 and 16 are required for QtBase.
      • Note that this is only necessary for building Qt itself. You can build Qt applications against any API level you wish, As long as it is equal to or higher than 13.
  2. You also need an Android NDK: https://developer.android.com/tools/sdk/ndk/index.html
    • Important: for Qt 5.12 downwards, GCC toolchains are used and Android NDK r10e is required.
    • Important: from Qt 5.12 onwards, the GCC toolchains are no longer supported in the Android NDK.
    • Important: For Qt 5.12.[0-5], and Qt 5.13.[0-1], Android NDK r19c is required.
    • Important: As of Qt 5.14, Qt 5.13.2+ and Qt 5.12.6+, the latest Android NDK (r20b or r21) is required. Qt 5.14.0 and 5.14.1 with NDK r21 might have a build issue that is solved at QTBUG-81461.
    • Important: If you are building Qt with the GCC toolchain (pre-Qt 5.12 only), you will need the Android NDK r10e. This is because NDK r11, r12 and r15 are known to have issues[1] with GCC. NDK r13 and r14 are also likely to have the same issues. r15 produces applications that fail with the error message 'This application failed to start because it could not find or load the Qt platform plugin "android"'. We recommend using the android-clang toolchain for compiling, in which case the latest NDK release should be preferred.
    • You need to make sure that the NDK supports the API level you're targeting. You can do this by checking the path-to-NDK/platforms directory.
  3. Install a JDK whose version is at least 1.6. This can be found on Oracle's website. Alternatively, OpenJDK can be used on Linux.
    apt-get install openjdk-8-jdk
    • If you're on a 64 bit Ubuntu/Debian, you may also need to install a 32-bit runtime environment:
      apt-get install libc6-i386

Building Qt

  1. Get Qt Creator 2.7.2 (or later): http://qt.io/download#qt-creator
  2. Get Qt 5:
    git clone git://code.qt.io/qt/qt5.git qt5
    cd qt5
    perl init-repository
  3. Optionally checkout target Qt version to use.
    git checkout v5.12.7
    git submodule update --recursive
  4. Configure Environment Variables.
    • You need to set JAVA_HOME and add JAVA_HOME/bin to your PATH. On Linux, a good place to do this is at the end of ~/.profile:
    export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64
    export PATH=$PATH:$JAVA_HOME/bin
  5. Configure Qt and skip unsupported modules:
    ./configure -xplatform android-clang --disable-rpath -nomake tests -nomake examples -android-ndk <path/to/ndk> -android-sdk <path/to/sdk> -android-ndk-host <e.g. linux-x86_64> -skip qttranslations -skip qtserialport -no-warnings-are-errors
    -android-ndk-host will be windows-x86_64 if you're on 64-bit Windows, for example. For more values, check qtbase/configure.pri.
    -android-abis starting with Qt 5.14 we'd added multi-abi build and you can use this parameter to filer the ABIs you want to build. By default is armeabi-v7a, arm64-v8a, x86, x86_64
    Note: the highest API level that the r10e NDK supports is 21, so it may be necessary to install that and then pass the following in addition to the arguments listed above:
    -android-ndk-platform android-21
    
  6. Build. Run the make command to build the configured Qt parts.
    make -j8
  7. Install. Run the make install command to install the built Qt parts. If you have not used the configure option --prefix <install-dir> the installation is done under the directory path /usr/local/Qt-<version>. Under Debian/Ubuntu you should prefix the make command with the sudo command.
    make install

Configuring Qt Creator

  1. Start the Qt Creator you built or downloaded earlier.
  2. Go into Tools -> Options -> Devices -> Android and set the right paths to Java, and the Android SDK and NDK, etc. For example:
    • JDK Location: /usr/lib/jvm/java-8-openjdk-amd64
    • Android SDK Location: /home/johnsmith/dev/android-sdk-tools
    • Android NDK Location: /home/johnsmith/dev/android-ndk-r19c
  3. Add your newly built Qt version to Tools -> Options -> Kits -> Qt Versions.
  4. Add a new kit using that Qt version (or clone an existing pre-built Qt for Android kit and just change the Qt version) in Tools -> Options -> Kits -> Kits.
  5. At this point, you should be able to create a project and configure it for the Android kit. In order to test, go into the Run settings for your project. Under Deploy Configuration, check the Use Qt libraries from the local device option. Also, select the Deploy local Qt libraries radio button.

References