안드로이드 배포 도구
안드로이드 패키지 빌드에는 많은 단계가 포함되므로 Qt에는 작업을 처리하는 도구가 함께 제공됩니다. androiddeployqt 도구가 처리하는 단계는 안드로이드에 애플리케이션 배포하기에서 설명합니다.
androiddeployqt를 실행하기 전 전제 조건
도구를 수동으로 실행하기 전에 CMake
또는 qmake
으로 프로젝트를 구성하여 Makefiles
및 JSON
파일(예: android-<target_name>-deployment-settings.json
)을 생성하여 androiddeployqt
에서 사용하는 중요한 설정을 포함해야 합니다.
참고: androiddeployqt JSON 파일은 수정하지 않는 것이 좋습니다.
안드로이드 배포를 위한 환경을 준비하려면 소스 디렉터리가 아닌 별도의 디렉터리에 프로젝트를 구성하세요. 프로젝트 구성에 대한 자세한 내용은 명령줄에서 안드로이드 프로젝트용 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를 실행하여 제외된 각 플러그인에 대한 누락된 종속성 목록을 확인할 수 있습니다. Projects > Build Steps > Build Android APK > Advanced Actions 에서 Verbose output 확인란을 선택하면 Qt Creator 에서도 동일한 결과를 얻을 수 있습니다.
애플리케이션의 종속성을 수동으로 지정할 수도 있습니다. 자세한 내용은 QT_ANDROID_DEPLOYMENT_DEPENDENCIES CMake 변수를 참조하세요.
참고: androiddeployqt는 프로젝트의 QML 파일을 스캔하여 QML 임포트를 수집합니다. 그러나 런타임에 C++에서 QString 로 QML 코드를 로드하는 경우 배포 시 androiddeployqt가 이를 인식하지 못하기 때문에 제대로 작동하지 않을 수 있습니다. 이 문제를 해결하려면 런타임에 참조되는 QML 모듈을 가져오는 더미 QML 파일을 추가할 수 있습니다.
배포 위치 Qt Creator
Qt Creator 는 androiddeployqt
을 사용하며, 다양한 옵션을 지정할 수 있는 쉽고 직관적인 사용자 인터페이스를 제공합니다. 자세한 내용은 Qt Creator: Android 기기에 애플리케이션 배포하기를 참조하세요.
Android용 Qt 앱 사용자 지정 및 배포에 대한 자세한 내용은 Android에 애플리케이션 배포하기를 참조하십시오.
© 2025 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.