Android에 애플리케이션 배포하기

이 문서에서는 Qt 애플리케이션을 Android 기기에 배포하는 데 필요한 기술적 단계를 설명합니다.

안드로이드 패키징 옵션

Android에서 코드를 패키징하는 방법에는 애플리케이션 패키지(APK), Android 앱 번들(AAB), Android 아카이브(AAR)의 세 가지가 있습니다. 각각은 미리 정의된 디렉터리 구조를 따르는 특정 유형의 ZIP 형식입니다. 이러한 형식 간의 차이점은 다음과 같습니다.

• APK 파일은 기기에 배포하여 실행할 수 있습니다.
• AAB는 Google Play 스토어에서 해석되도록 설계되었으며, 다양한 기기 아키텍처 및 폼 팩터에 맞는 APK 파일을 생성하는 데 사용됩니다.
• AAR은 안드로이드 라이브러리라는 점에서 APK 및 AAB 형식과 근본적으로 다릅니다. 안드로이드 앱 모듈의 종속성으로 사용할 수 있지만, 단독으로는 실행할 수 없습니다. 자세한 내용은 Android: Android Archive(AAR)을 참조하세요.

Android 애플리케이션 번들

로컬에서 애플리케이션을 테스트할 때는 기기에 직접 설치하여 실행할 수 있는 APK 형식이 적합합니다. Google Play 스토어에 배포할 때는 레이아웃이 유사한 AAB를 사용하는 것이 권장됩니다. AAB의 또 다른 장점은 사용자가 다운로드하는 실제 패키지 크기를 늘리지 않고도 모든 대상 ABI를 동일한 번들에 포함할 수 있다는 점입니다. AAB를 사용할 경우, Google Play 스토어는 다운로드 요청을 보낸 기기에 맞게 최적화된 APK 패키지를 생성하고, 게시자 키로 자동으로 서명합니다. 자세한 내용은 Google Play에 게시하기를 참조하세요.

AAB 형식에 대한 자세한 내용은 ‘Android 앱 번들’을 참조하세요.

두 경우 모두, 애플리케이션 번들은 프로젝트의 ` shared ` 라이브러리와 애플리케이션에 필요한 Qt의 종속성을 포함하는 특정 디렉터리 구조에서 생성됩니다. 또한 모든 자산, 리소스, ` jar ` 파일 또는 프로젝트 Java 코드가 컴파일되어 포함됩니다.

애플리케이션 번들 생성

Android용 Qt 앱을 배포할 때는 Qt Creator 를 사용하는 것이 좋습니다. 그렇지 않은 경우, CMake 또는 qmake를 활용하여 명령줄을 통해 동일한 작업을 수행할 수 있습니다. 자세한 내용은 ‘명령줄에서 Android용 Qt 프로젝트 빌드하기’를 참조하십시오.

패키징 및 배포 프로세스는 CMake 또는 qmake에 의해 처리되며, 이 도구들은 내부적으로 androiddeployqt 도구를 사용하여 Android 앱 빌드 및 배포의 세부 사항을 관리합니다. Qt Creator 도 동일한 도구를 사용합니다.

Android 기능을 활용한 Qt 확장

기본적으로 Qt for Android는 안드로이드 앱을 구동하기 위해 필요한 대부분의 복잡한 작업을 처리하며, 가장 유용한 API는 Qt에서 직접 사용할 수 있고, 즉시 사용할 수 없는 API는 QJniObject 를 통해 호출할 수 있습니다. 다양한 빌드 및 배포 시나리오를 처리하는 CMake도 마찬가지입니다. 그러나 경우에 따라 Java/Kotlin 코드를 작성하거나 Android 리소스 관리 기능을 사용하는 등, 네이티브 Android 기능의 모든 성능을 활용해야 할 수도 있습니다. Qt는 사용자가 템플릿 세트를 확장할 수 있도록 허용함으로써 이를 가능하게 합니다.

Qt에서 사용하는 기본 템플릿은 Qt for Android 설치 경로, 예를 들어 Unix의 경우 ~/Qt/<version>/android_<abi>/src/android/templates 하위에 있습니다. 이러한 템플릿을 사용하려면 Qt Creator 를 통해 프로젝트로 복사할 수 있습니다. 자세한 내용은 Qt Creator: Android Deploy Qt를 참조하십시오. 또는 android 하위 디렉터리에 해당 템플릿을 프로젝트 소스 디렉터리로 수동으로 복사할 수도 있습니다. 그런 다음 CMakeLists.txt 파일에 다음 속성을 반드시 정의해야 합니다:

set_property(TARGET target_name PROPERTY QT_ANDROID_PACKAGE_SOURCE_DIR
          "${CMAKE_CURRENT_SOURCE_DIR}/android")

또는 qmake를 사용하는 경우, ` pro ` 파일에 다음을 추가하세요:

android: ANDROID_PACKAGE_SOURCE_DIR = $$PWD/android

빌드 프로세스는 프로젝트에서 템플릿을 <build_path>/android-build 디렉터리로 복사하거나, 프로젝트에서 QT_ANDROID_PACKAGE_SOURCE_DIR 를 설정하지 않은 경우 기본 템플릿을 사용합니다. 그 후, <build_path>/android-build 디렉터리가 패키징 디렉터리로 사용됩니다. 애플리케이션 번들은 Gradle을 사용하여 해당 디렉터리에서 생성됩니다.

QT_ANDROID_GRADLE_MULTI_MODULE가 활성화된 경우, 패키징 디렉터리에는 대신 다중 모듈로 구성된 Gradle 프로젝트가 포함됩니다. 그런 다음 애플리케이션은 <build_path>/android-build/app 에서 패키징되며, 각 동적 기능은 그 옆에 별도의 모듈을 갖게 됩니다.

이제 기본 템플릿을 확장한 후 사용자가 작업할 수 있는 여러 부분을 살펴보겠습니다.

AndroidManifest.xml

AndroidManifest.xml 파일은 애플리케이션에 대한 상세한 메타 정보를 제공합니다. 이 정보는 애플리케이션 번들을 맞춤 설정하는 데 사용되며, 기기에서 애플리케이션의 기본 방향과 같은 기능을 활성화할지 여부를 결정하는 데 활용됩니다. 또한 Google Play 스토어에서는 버전 코드, 기기 지원, 패키지 이름 등 다양한 정보를 확인하는 데 이 파일을 사용합니다. Android 매니페스트는 Android 서비스와 사용자 정의 Android 액티비티를 정의하는 데에도 사용됩니다.

AndroidManifest.xml 에 대한 자세한 내용은 Android 매니페스트 파일 문서와{Qt Creator: Android 배포 구성}{매니페스트 파일 편집}을 참조하십시오.

Gradle 파일

Gradle은 Android 패키지를 빌드하는 데 사용됩니다. Qt에는 두 가지 유형의 Gradle 관련 파일이 포함되어 있습니다:

• Gradle 자체의 특정 버전을 다운로드하는 데 사용되는 Gradle 래퍼와, Gradle 빌드를 호출하는 데 사용되는 빌드 스크립트입니다. 이러한 파일들은 예를 들어 ~/Qt/<version>/android_<abi>/src/3rdparty/gradle 경로에서 Qt와 함께 제공됩니다.

  참고: 일반적으로 Qt에 포함된 것과 동일한 Gradle 버전을 사용하는 것이 권장됩니다. 하지만 다른 Gradle 버전을 사용하고자 하는 경우, Gradle 래퍼( gradle-wrapper.properties )를 수정하여 사용하고자 하는 Gradle 버전으로 설정할 수 있습니다.

• Android Templates 디렉터리에 있는 Gradle 구성 파일( build.gradle)입니다. 이 파일은 Gradle에서 필수로 요구하며, 빌드를 사용자 정의하는 데 사용할 수 있습니다. 이 파일을 통해 빌드 대상이나 최소 API를 설정하거나 라이브러리 종속성을 추가할 수 있습니다. 또한 Android 앱 빌드에 필수적인 Gradle 종속성인 Android Gradle 플러그인을 설정하는 데도 사용할 수 있습니다. 다음은 그 예시입니다:

  buildscript {
      ...
      dependencies {
          classpath 'com.android.tools.build:gradle:9.2.1'
      }
  }

  자세한 내용은 Android: 빌드 구성 파일을 참조하세요.

Java/Kotlin 코드

Qt에서 지원하지 않는 API를 사용하거나 다른 이유로 Java/Kotlin 코드를 포함하려면, 해당 코드를 <QT_ANDROID_PACKAGE_SOURCE_DIR>/src/ 경로 아래에 배치하십시오. 예를 들어, Qt 코드 내에서 Java 메서드를 호출할 수 있습니다. 예제는 ‘Qt for Android 알림 예제’를 참조하십시오.

리소스

Android에서는 아이콘, 이미지, 문자열, 색상 등과 같은 리소스 파일을 추가할 수 있습니다. 이러한 리소스는 Java/Kotlin 코드나 매니페스트 파일에서 직접 참조할 수 있습니다. 이러한 파일은 모두 <QT_ANDROID_PACKAGE_SOURCE_DIR>/res/ 경로 아래에 프로젝트에 추가할 수 있습니다. 예를 들어, 앱 아이콘은 res/drawable/icon.png 경로 아래에 추가할 수 있습니다.

자세한 내용은 ‘Android: 앱 리소스 개요’를 참조하세요.

Qt 내부 리소스

기본적으로 Qt는 앱이 정상적으로 실행되는 데 필요한 몇 가지 리소스를 패키지에 포함합니다. 예를 들어, Unix 환경에서는 이러한 리소스가 ` ~/Qt/<version>/android_<abi>/src/android/templates/res` 경로에 있습니다.

strings.xml

이 파일은 res/values/strings.xml 경로에서 찾을 수 있습니다. 이 파일에는 Qt 라이브러리가 다양한 언어의 메시지 번역을 참조하는 데 사용하는 문자열이 포함되어 있습니다.

libs.xml

이 파일은 res/values/libs.xml 에서 찾을 수 있습니다. 이 파일은 오로지 Qt 라이브러리의 배포 정보를 관리하는 데 사용되며, 수동으로 수정하는 것은 권장되지 않습니다.

Android 자산

Android 자산 관리에 대한 자세한 내용은 ‘리소스 추가’를 참조하십시오.

Android 라이브러리

Qt 프로젝트에서 타사 라이브러리를 사용하는 방법에 대한 자세한 내용은 ‘Android 프로젝트에 라이브러리 포함’을 참조하십시오.