diff options
Diffstat (limited to 'src/tools/androiddeployqt/doc/src/androiddeployqt.qdoc')
| -rw-r--r-- | src/tools/androiddeployqt/doc/src/androiddeployqt.qdoc | 237 |
1 files changed, 43 insertions, 194 deletions
diff --git a/src/tools/androiddeployqt/doc/src/androiddeployqt.qdoc b/src/tools/androiddeployqt/doc/src/androiddeployqt.qdoc index b77d3182c5..b94d7f5c04 100644 --- a/src/tools/androiddeployqt/doc/src/androiddeployqt.qdoc +++ b/src/tools/androiddeployqt/doc/src/androiddeployqt.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2021 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$ -** -****************************************************************************/ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page android-deploy-qt-tool.html @@ -31,132 +7,47 @@ \title The androiddeployqt Tool \target androiddeployqt - Building an application package is complex, so Qt comes with a tool which - handles the work for you. The steps described in - \l{Deploying an Application on Android} are handled by the androiddeployqt - tool. + Building an Android package involves many steps, so Qt comes with a tool which + handles the work for you. The steps handled by the androiddeployqt + tool are described in \l{Deploying an Application on Android}. \section1 Prerequisites Before Running androiddeployqt - Before running the tool manually, you need to run \c qmake or \c CMake - on your project to generate \c Makefiles and a \c JSON file (i.e. - \c{android-project-deployment-settings.json}) containing important settings + Before running the tool manually, you need to configure your project with + \c CMake or \c qmake to generate \c Makefiles and a \c JSON file (i.e. + \c{android-<target_name>-deployment-settings.json}) containing important settings used by \c androiddeployqt. \note It is not recommended to modify the androiddeployqt JSON file. - To prepare the build for androiddeployqt, it is recommended to build your - project in a separate directory. Run the following commands: + To prepare the environment for androiddeployqt, configure your project in + a separate directory than your source directory. For more information on + configuring your project, see \l {Building Qt for Android Projects from Command Line}. + \section1 Command Line Arguments - \badcode - mkdir build-project - cd build-project - \endcode - - Followed by: - - For qmake: - \badcode - qmake ../project/project.pro - make -j$(nproc) - make -j$(nproc) apk_install_target - \endcode - - For CMake: - \badcode - cmake --build - \endcode + The only required command line arguments when running the tool are + \c {--input} and \c {--output}. Other command line arguments are optional but + useful. The list below is available by passing the \c {--help} argument to + androiddeployqt. - \section1 Command Line Arguments + \quotefromfile main.cpp + \skipto Syntax: androiddeployqt --output <destination> [options] + \printuntil --help: Displays this information. - The only required command line argument when running the tool is \c{--output}. - 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. - - \table - \header - \li Argument - \li Brief Description - \row - \li \c{--output <destination>} - \li Specifies the destination of the final package. Set this to - \c{$ANDROID_BUILD_DIR}, that is the build directory where you installed - your application binaries. - \row - \li \c{--input <file name>} - \li This allows you to specify the generated \c JSON settings file. - \c androiddeployqt will try to guess the file name based on the - current working directory. - \row - \li \c{--aab} - \li Generate an Android Application Bundle, rather than an APK. Note - that this invalidates some of the other arguments, such as \c{--install}. - \row - \li \c{--deployment <mechanism>} - \li Specify this to pick a different deployment mechanism than the - default. - \row - \li \c{--install} - \li 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. - \row - \li \c{--device <ID>} - \li 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. - \row - \li \c{--android-platform <platform>} - \li The SDK platform used for building the Java code of the application. - By default, the latest available platform is used. - \row - \li \c{--release} - \li 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. - \row - \li \c{--sign <url> <alias>} - \li 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. Optionally, set the following environment - variables to conceal the signing information - \c QT_ANDROID_KEYSTORE_PATH, \c QT_ANDROID_KEYSTORE_ALIAS, - \c QT_ANDROID_KEYSTORE_STORE_PASS, and \c QT_ANDROID_KEYSTORE_KEY_PASS. - 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. - \row - \li \c{--jdk <path>} - \li 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. - \row - \li \c{--verbose} - \li Specify this to output more information about what \c androiddeployqt is - doing. - \row - \li \c{--help} - \li Prints the help for the tool. - \endtable - - With a project named \c project, to directly build the application package - with \c androiddeployqt without deploying it the device, run the following: + With a \c project_name, to build the application package with \c androiddeployqt + without deploying it the device, run the following: \badcode - .androiddeployqt --input $BUILD_DIR/android-project-deployment-settings.json --output $ANDROID_BUILD_DIR + androiddeployqt --input <build_dir>/android-project_name-deployment-settings.json \ + --output <build_dir>/android-build \endcode - To deploy the built package to the device: + To build and deploy the package to the device: \badcode - androiddeployqt --verbose --output $ANDROID_BUILD_DIR --no-build --input $BUILD_DIR/android-project-deployment-settings.json --gradle --reinstall --device <adb_device_id> + androiddeployqt --input <build_dir>/android-project_name-deployment-settings.json \ + --output <build_dir>/android-build --install --device <device_serial_id> \endcode \section1 Dependencies Detection @@ -168,11 +59,13 @@ 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 \l{Qt SVG} + the SVG image format plugin is included, you will need to add \l {Qt SVG} module to your project for it to become a dependency of your application: \badcode - QT += svg + find_package(Qt6 REQUIRED COMPONENTS Svg) + ... + target_link_libraries(target_name PRIVATE Qt6::Svg) \endcode If you are wondering why a particular plugin is not included automatically, @@ -183,64 +76,20 @@ \uicontrol {Advanced Actions}. It's also possible to manually specify the dependencies of your application. - For more information, see \l{ANDROID_DEPLOYMENT_DEPENDENCIES} qmake variable. - - \section1 Android-specific qmake Variables - - Unless the project has special requirements such as third party libraries, - it should be possible to run \l androiddeployqt on it with no modifications - and get a working Qt for Android application. - - There are two important environment variables used by Qt: - - \list - \li \c{ANDROID_SDK_ROOT}: specifies the path to the Android SDK used for - building the application. The Android SDK contains the build-tools, - Android NDK, and Android toolchains. - \li \c{ANDROID_NDK_ROOT}: specifies the path to the Android NDK used to - build the application. It is not recommended to hard-code this path, - since different Qt for Android versions can depend on different - Android NDK versions. - \endlist - - \note Qt Creator sets these variables by default. - - There are a set of \c qmake or \c CMake variables that can be used to tailor - your package. At some point during development, you will most likely want - to look into these variables to customize your application. - - Here is a list of some variables that are particularly interesting when - making Android applications: - - \list - \li \l{ANDROID_PACKAGE_SOURCE_DIR} - \li \l{ANDROID_VERSION_CODE} - \li \l{ANDROID_VERSION_NAME} - \li \l{ANDROID_EXTRA_LIBS} - \li \l{ANDROID_EXTRA_PLUGINS} - \li \l{ANDROID_ABIS} - \li \l{ANDROID_API_VERSION} - \li \l{ANDROID_DEPLOYMENT_DEPENDENCIES} - \li \l{ANDROID_MIN_SDK_VERSION} - \li \l{ANDROID_TARGET_SDK_VERSION} - \li \l{JAVA_HOME} - \endlist - - Also, the following \c qmake variables are primarily useful when writing a Qt module, and not - normal applications: - - \list - \li \l{ANDROID_BUNDLED_JAR_DEPENDENCIES} - \li \l{ANDROID_LIB_DEPENDENCIES} - \li \l{ANDROID_PERMISSIONS} - \li \l{ANDROID_FEATURES} - \endlist - - \note This list of variables can also be used with CMake. + For more information, see \l {QT_ANDROID_DEPLOYMENT_DEPENDENCIES} CMake variable. + + \note androiddeployqt scans the QML files of the project to collect the QML imports. + However, if you are loading QML code as a QString from C++ at runtime, that might + not work properly because androiddeployqt won't be aware of it at deploy time. + To remedy that, you can add a dummy QML file that imports such QML modules that + are referenced at runtime. \section1 Deployment in Qt Creator - Qt Creator runs \c androiddeployqt by default, 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}. + Qt Creator uses \c androiddeployqt under the hood, and provides easy + and intuitive user interfaces to specify various options. For more information, + see \l{Qt Creator: Deploying Applications to Android Devices}. + + For more information about customizing and deploying a Qt for Android app, + see \l {Deploying an Application on Android}. */ |