diff options
Diffstat (limited to 'src/tools/androiddeployqt/doc/src/androiddeployqt.qdoc')
-rw-r--r-- | src/tools/androiddeployqt/doc/src/androiddeployqt.qdoc | 95 |
1 files changed, 95 insertions, 0 deletions
diff --git a/src/tools/androiddeployqt/doc/src/androiddeployqt.qdoc b/src/tools/androiddeployqt/doc/src/androiddeployqt.qdoc new file mode 100644 index 0000000000..b94d7f5c04 --- /dev/null +++ b/src/tools/androiddeployqt/doc/src/androiddeployqt.qdoc @@ -0,0 +1,95 @@ +// 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 + \brief An overview of the androiddeployqt tool and how to use it. + \title The androiddeployqt Tool + + \target androiddeployqt + 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 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 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 + + 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. + + \quotefromfile main.cpp + \skipto Syntax: androiddeployqt --output <destination> [options] + \printuntil --help: Displays this information. + + 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_name-deployment-settings.json \ + --output <build_dir>/android-build + \endcode + + To build and deploy the package to the device: + + \badcode + androiddeployqt --input <build_dir>/android-project_name-deployment-settings.json \ + --output <build_dir>/android-build --install --device <device_serial_id> + \endcode + + \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 \l {Qt SVG} + module to your project for it to become a dependency of your application: + + \badcode + 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, + 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 \uicontrol {Verbose output} check box in the + \uicontrol {Projects} > \uicontrol {Build Steps} > \uicontrol {Build Android APK} > + \uicontrol {Advanced Actions}. + + It's also possible to manually specify the dependencies of your application. + 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 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}. +*/ |