androiddeployqt 도구
Android 패키지를 빌드하는 데는 여러 단계가 필요하므로, Qt에는 이 작업을 대신 처리해 주는 도구가 포함되어 있습니다. Android Deploy Qt 도구가 처리하는 단계에 대해서는 ‘Android에 애플리케이션 배포하기’에서 설명하고 있습니다.
androiddeployqt 실행 전 준비 사항
이 도구를 수동으로 실행하기 전에, CMake 또는 qmake 을 사용하여 프로젝트를 구성해야 합니다. 이를 통해 Makefiles 파일과 androiddeployqt 에서 사용하는 중요한 설정이 포함된 JSON 파일(예: android-<target_name>-deployment-settings.json)이 생성됩니다.
참고: androiddeployqt JSON 파일을 수정하는것은 권장되지 않습니다.
androiddeployqt를 위한 환경을 준비하려면, 소스 디렉터리와는 다른 디렉터리에 프로젝트를 구성하십시오. 프로젝트 구성에 대한 자세한 내용은 ‘명령줄에서 Android용 Qt 프로젝트 빌드’를 참조하십시오.
명령줄 인수
이 도구를 실행할 때 필수로 지정해야 하는 명령줄 인수는 ` --input ` 및 ` --output` 뿐입니다. 다른 명령줄 인수는 선택 사항이지만 유용합니다. 아래 목록은 androiddeployqt에 ` --help ` 인수를 전달하면 확인할 수 있습니다.
Syntax: androiddeployqt --output <destination> [options]
Creates an Android package in the build directory <destination> and
builds it into an .apk file.
Optional arguments:
--input <inputfile>: Reads <inputfile> for options generated by
qmake. A default file name based on the current working
directory will be used if nothing else is specified.
--deployment <mechanism>: Supported deployment mechanisms:
bundled (default): Includes Qt files in stand-alone package.
unbundled: Assumes native libraries are present on the device
and does not include them in the APK.
--aab: Build an Android App Bundle.
--no-build: Do not build the package, it is useful to just install
a package previously built.
--install: Installs apk to device/emulator. By default this step is
not taken. If the application has previously been installed on
the device, it will be uninstalled first.
--reinstall: Installs apk to device/emulator. By default this step
is not taken. If the application has previously been installed on
the device, it will be overwritten, but its data will be left
intact.
--device [device ID]: Use specified device for deployment. Default
is the device selected by default by adb.
--android-platform <platform>: Builds against the given android
platform. By default, the highest available version will be
used.
--release: Builds a package ready for release. By default, the
package will be signed with a debug key.
--sign <url/to/keystore> <alias>: Signs the package with the
specified keystore, alias and store password.
Optional arguments for use with signing:
--storepass <password>: Keystore password.
--storetype <type>: Keystore type.
--keypass <password>: Password for private key (if different
from keystore password.)
--sigfile <file>: Name of .SF/.DSA file.
--digestalg <name>: Name of digest algorithm. Default is
"SHA-256".
--sigalg <name>: Name of signature algorithm. Default is
"SHA256withRSA".
--tsa <url>: Location of the Time Stamping Authority.
--tsacert <alias>: Public key certificate for TSA.
--internalsf: Include the .SF file inside the signature block.
--sectionsonly: Do not compute hash of entire manifest.
--protected: Keystore has protected authentication path.
--jarsigner: Deprecated, ignored.
NOTE: To conceal the keystore information, the environment variables
QT_ANDROID_KEYSTORE_PATH, and QT_ANDROID_KEYSTORE_ALIAS are used to
set the values keysotore and alias respectively.
Also the environment variables QT_ANDROID_KEYSTORE_STORE_PASS,
and QT_ANDROID_KEYSTORE_KEY_PASS are used to set the store and key
passwords respectively. This option needs only the --sign parameter.
--jdk <path/to/jdk>: Used to find the jarsigner tool when used
in combination with the --release argument. By default,
an attempt is made to detect the tool using the JAVA_HOME and
PATH environment variables, in that order.
--qml-import-paths: Specify additional search paths for QML
imports.
--verbose: Prints out information during processing.
--no-generated-assets-cache: Do not pregenerate the entry list for
the assets file engine.
--aux-mode: Operate in auxiliary mode. This will only copy the
dependencies into the build directory and update the XML templates.
The project will not be built or installed.
--apk <path/where/to/copy/the/apk>: Path where to copy the built apk.
--build-aar: Build an AAR package. This option skips --aab, --install,
--reinstall, and --sign options if they are provided.
--qml-importscanner-binary <path/to/qmlimportscanner>: Override the
default qmlimportscanner binary path. By default the
qmlimportscanner binary is located using the Qt directory
specified in the input file.
--depfile <path/to/depfile>: Output a dependency file.
--builddir <path/to/build/directory>: build directory. Necessary when
generating a depfile because ninja requires relative paths.
--no-rcc-bundle-cleanup: skip cleaning rcc bundle directory after
running androiddeployqt. This option simplifies debugging of
the resource bundle content, but it should not be used when deploying
a project, since it litters the "assets" directory.
--copy-dependencies-only: resolve application dependencies and stop
deploying process after all libraries and resources that the
application depends on have been copied.
--help: Displays this information.project_name 를 사용하여 androiddeployqt 로 애플리케이션 패키지를 빌드하되 기기에 배포하지 않으려면 다음 명령을 실행하십시오:
androiddeployqt --input <build_dir>/android-project_name-deployment-settings.json \
--output <build_dir>/android-build패키지를 빌드하고 기기에 배포하려면:
androiddeployqt --input <build_dir>/android-project_name-deployment-settings.json \
--output <build_dir>/android-build --install --device <device_serial_id>의존성 탐지
Qt에는 필요할 때 런타임에 로드되는 다양한 플러그인이 포함되어 있습니다. 이러한 플러그인은 SQL 데이터베이스 연결부터 특정 이미지 형식 로딩에 이르기까지 다양한 작업을 처리할 수 있습니다. 플러그인이 런타임에 로드되기 때문에 플러그인 종속성을 정확히 탐지하는 것은 불가능하지만, androiddeployqt는 애플리케이션의 Qt 종속성을 바탕으로 이러한 종속성을 추측합니다. 플러그인에 애플리케이션의 종속성이 아닌 Qt 종속성이 포함되어 있다면, 해당 플러그인은 기본적으로 포함되지 않습니다. 예를 들어, SVG 이미지 형식 플러그인이 포함되도록 하려면, 해당 플러그인이 애플리케이션의 종속성이 되도록 하려면 프로젝트에 Qt SVG 모듈을 추가하여 이를 애플리케이션의 의존성으로 지정해야 합니다:
find_package(Qt6 REQUIRED COMPONENTS Svg)
...
target_link_libraries(target_name PRIVATE Qt6::Svg)특정 플러그인이 자동으로 포함되지 않는 이유가 궁금하다면, ` --verbose ` 옵션을 사용하여 androiddeployqt를 실행하면 제외된 각 플러그인에 대해 누락된 종속성 목록을 확인할 수 있습니다. Qt Creator 에서 ` Projects ` > ` Build Steps ` > ` Build Android APK ` > ` Advanced Actions` 경로에서 ` Verbose output ` 확인란을 선택해도 동일한 결과를 얻을 수 있습니다.
또한 애플리케이션의 종속성을 수동으로 지정할 수도 있습니다. 자세한 내용은 QT_ANDROID_DEPLOYMENT_DEPENDENCIES CMake 변수를 참조하십시오.
참고: androiddeployqt는 프로젝트의 QML 파일을 스캔하여 QML 임포트 정보를 수집합니다. 그러나 런타임에 C++에서 QML 코드를 ` QString `로 불러오는 경우, 배포 시점에 androiddeployqt가 이를 인식하지 못하므로 제대로 작동하지 않을 수 있습니다. 이를 해결하려면, 런타임에 참조되는 해당 QML 모듈을 임포트하는 더미 QML 파일을 추가할 수 있습니다.
배포 시 Qt Creator
Qt Creator 는 내부적으로 androiddeployqt 를 사용하며, 다양한 옵션을 지정할 수 있는 쉽고 직관적인 사용자 인터페이스를 제공합니다. 자세한 내용은 Qt Creator: Android 배포 구성을 참조하십시오.
Qt for Android 앱의 사용자 지정 및 배포에 대한 자세한 내용은 ‘Android에 애플리케이션 배포’를 참조하십시오.
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.