명령줄에서 앱 빌드

Android 프로젝트에서 Gradle 래퍼 명령줄 도구 사용

Gradle 래퍼 명령줄 도구를 사용해 Android 프로젝트에 사용 가능한 모든 빌드 작업을 실행할 수 있습니다. Windows에는 배치 파일(gradlew.bat)로, Linux와 Mac에는 셸 스크립트(gradlew.sh)로 사용할 수 있고, Android 스튜디오로 생성하는 각 프로젝트의 루트에서 액세스 가능합니다.

래퍼로 작업을 실행하려면 터미널 창(Android 스튜디오에서 View > Tool Windows > Terminal 선택)에서 다음 명령 중 하나를 사용합니다.

  • Windows:
    gradlew task-name
  • Mac 또는 Linux:
    ./gradlew task-name

프로젝트에 사용 가능한 모든 빌드 작업의 목록을 보려면 tasks를 실행합니다.

    gradlew tasks
    

이 페이지의 나머지 부분에서는 Gradle 래퍼로 앱을 빌드하고 실행하기 위한 기본 사항을 설명합니다. Android 빌드 설정 방법에 관한 자세한 정보는 빌드 구성을 참조하세요.

명령줄 도구 대신 Android 스튜디오 도구를 사용하려면 앱 빌드 및 실행을 참조하세요.

빌드 유형 정보

어떤 Android 앱에서든 기본적으로 두 가지 빌드 유형을 사용할 수 있습니다. 하나는 앱을 디버그하기 위한 빌드이고(디버그 빌드), 다른 하나는 앱을 사용자에게 릴리스하기 위한 빌드입니다(릴리스 빌드). 앱을 기기에 배포하려면 먼저 인증서로 각 빌드의 결과 출력에 서명해야 합니다. 디버그 빌드는 SDK 도구에서 제공되는 디버그 키로 자동으로 서명되며(안전하지 않으므로 이 키로 Google Play 스토어에 게시할 수 없음), 릴리스 빌드는 자신의 비공개 키로 서명해야 합니다.

릴리스할 앱을 빌드하려면 적절한 서명 키로 앱에 서명하는 것이 중요합니다. 하지만 이제 막 시작한 초보자라면 디버그 APK를 빌드하여 에뮬레이터나 연결된 기기에서 앱을 빠르게 실행할 수 있습니다.

build.gradle 파일에서 맞춤형 빌드 유형을 정의하고, 여기에 debuggable true를 포함하여 이 유형이 디버그 빌드로서 서명되도록 구성할 수도 있습니다. 자세한 내용은 빌드 변형 구성을 참조하세요.

APK 빌드 및 배포

앱을 패키지로 만들어 Play Console에 업로드하는 가장 좋은 방법은 App Bundle을 빌드하는 것이지만, 디버그 빌드를 빠르게 테스트하거나 앱을 배포 가능한 아티팩트로서 타인과 공유하려면 APK를 빌드하는 것이 더 낫습니다.

디버그 APK 빌드

디버그 APK를 빌드하면 앱을 즉시 테스트하고 디버그할 수 있습니다. 디버그 APK는 SDK 도구에서 제공하는 디버그 키로 서명되며 adb를 통한 디버깅을 허용합니다.

디버그 APK를 빌드하려면 명령줄을 열고 프로젝트 디렉터리의 루트로 이동합니다. 디버그 빌드를 시작하려면 assembleDebug 작업을 호출합니다.

    gradlew assembleDebug
    

그러면 project_name/module_name/build/outputs/apk/module_name-debug.apk라는 이름의 APK가 생성됩니다. 이 파일은 이미 디버그 키로 서명되고 zipalign으로 정렬되어 있으므로 기기에 바로 설치할 수 있습니다.

또는 APK를 빌드하고 실행 중인 에뮬레이터나 연결된 기기에 즉시 설치하려면, 대신 아래와 같이 installDebug를 호출합니다.

gradlew installDebug

위 작업 이름의 'Debug' 부분은 빌드 변형 이름의 영문 표기일 뿐이므로 어셈블하거나 설치하려는 빌드 유형 또는 변경으로 교체할 수 있습니다. 예를 들어 'demo' 제품 버전이 있는 경우 assembleDemoDebug 작업으로 디버그 버전을 빌드할 수 있습니다.

제거 작업을 포함하여 각 변형에 사용 가능한 모든 빌드 및 설치 작업을 보려면 tasks 작업을 실행합니다.

에뮬레이터에서 앱 실행기기에서 앱 실행 방법에 관한 섹션도 참조하세요.

릴리스 APK 빌드

앱을 릴리스하고 배포할 준비가 되면 비공개 키로 서명된 릴리스 APK를 빌드해야 합니다. 자세한 내용은 명령줄에서 앱에 서명하는 방법에 관한 섹션에서 확인하세요.

에뮬레이터에 앱 배포

Android 에뮬레이터를 사용하려면 Android 스튜디오로 AVD(Android 가상 기기)를 생성해야 합니다.

AVD가 생성되면 Android 에뮬레이터를 시작하고 다음과 같이 앱을 설치하세요.

  1. 명령줄에서 android_sdk/tools/로 이동하고 AVD를 지정하여 에뮬레이터를 시작합니다.

    emulator -avd avd_name

    AVD 이름을 확실히 알지 못하면 emulator -list-avds를 실행합니다.

  2. 이제 디버그 APK 빌드 방법 또는 adb 도구 섹션에 나와 있는 Gradle 설치 작업 중 하나를 사용하여 앱을 설치할 수 있습니다.

    APK가 개발자 미리보기 SDK를 사용하여 빌드된 경우(targetSdkVersion이 숫자가 아닌 문자인 경우), 테스트 APK를 설치하기 위한 install 명령에 -t 옵션을 포함해야 합니다.

        adb install path/to/your_app.apk
        

    빌드한 모든 APK는 project_name/module_name/build/outputs/apk/에 저장됩니다.

자세한 정보는 Android 에뮬레이터에서 앱 실행을 참조하세요.

물리적 기기에 앱 배포

기기에서 앱을 실행할 수 있으려면 먼저 기기에서 USB 디버깅을 활성화해야 합니다. 이 옵션은 설정 > 개발자 옵션에서 찾을 수 있습니다.

참고: Android 4.2 이상의 버전에서는 개발자 옵션이 기본적으로 숨겨져 있습니다. 이 옵션을 사용하려면 설정 > 휴대전화 정보로 이동하여 빌드 번호를 7번 탭합니다. 이전 화면으로 돌아가서 개발자 옵션을 찾습니다.

기기를 설정하고 USB를 통해 연결했으면 디버그 APK 빌드 방법 관련 섹션에 나와 있는 Gradle 설치 작업 또는 adb 도구를 사용하여 앱을 설치할 수 있습니다.

    adb -d install path/to/your_app.apk
    

빌드한 모든 APK는 project_name/module_name/build/outputs/apk/에 저장됩니다.

자세한 내용은 하드웨어 기기에서 앱 실행을 참조하세요.

App Bundle 빌드

Android App Bundle에는 모든 앱의 컴파일된 코드 및 리소스가 포함되어 있지만, APK 생성 및 Google Play 서명은 연기됩니다. APK와 달리 App Bundle은 기기에 직접 배포할 수 없습니다. APK를 빠르게 테스트하고 타인과 공유하려면 대신 APK를 빌드해야 합니다.

App Bundle을 빌드하는 가장 쉬운 방법은 Android 스튜디오를 사용하는 것입니다. 그러나 명령줄에서 App Bundle을 빌드해야 하는 경우, 아래 섹션에 나와 있는 대로 Gradle 또는 bundletool을 사용할 수 있습니다.

Gradle로 App Bundle 빌드

명령줄에서 App Bundle을 생성하려면 앱의 기본 모듈에서 bundleVariant Gradle 작업을 실행합니다. 예를 들어, 다음 명령은 기본 모듈의 디버그 버전에 대한 App Bundle을 빌드합니다.

./gradlew :base:bundleDebug
    

Play Console에 업로드하기 위한 서명된 App Bundle을 빌드하려면 먼저 앱의 서명 정보로 기본 모듈의 build.gradle 파일을 구성해야 합니다. 자세히 알아보려면 앱에 서명하도록 Gradle을 구성하는 방법에 관한 섹션으로 이동하세요. 그런 다음, 예를 들어 앱의 릴리스 버전을 빌드할 수 있습니다. 그러면 Gradle은 App Bundle을 자동으로 생성하고 build.gradle 파일에 제공된 서명 정보로 서명합니다.

위의 방법 대신 별도의 단계로 App Bundle에 서명하려면 jarsigner를 사용하여 명령줄에서 App Bundle에 서명할 수 있습니다.

bundletool을 사용하여 App Bundle 빌드

bundletool은 Android 스튜디오, Android Gradle 플러그인 및 Google Play에서 앱의 컴파일된 코드 및 리소스를 App Bundle로 변환하고 여기에서 배포 가능한 APK를 생성하기 위해 사용하는 명령줄 도구입니다.

따라서 bundletool로 App Bundle을 테스트하고 Google Play에서 APK를 생성하는 방법을 로컬에서 재현하는 것이 유용하기는 하지만, 일반적으로 App Bundle 자체를 빌드하기 위해 bundletool을 호출할 필요는 없습니다. 대신 이전 섹션에서 설명한 대로 Android 스튜디오 또는 Gradle 작업을 사용해야 합니다.

그러나 App Bundle을 빌드하는 데 Android 스튜디오 또는 Gradle 작업을 사용하지 않으려는 경우(예를 들어 맞춤형 빌드 도구 모음을 사용하는 경우), 명령줄에서 bundletool을 사용하여 사전 컴파일된 코드 및 리소스에서 App Bundle을 빌드할 수 있습니다. 아직 하지 않았으면 GitHub 저장소에서 bundletool을 다운로드합니다.

이 섹션에서는 앱의 컴파일된 코드 및 리소스를 패키지화하는 방법과 명령줄에서 bundletool을 사용하여 Android App Bundle로 변환하는 방법을 설명합니다.

proto 형식으로 매니페스트 및 리소스 생성

bundletool에는 앱의 매니페스트 및 리소스와 같은 앱 프로젝트에 관한 Google의 프로토콜 버퍼 형식('protobuf'라고도 하며 *.pb 파일 확장자를 사용함)이 필요합니다. Protobuf는 구조화된 데이터 직렬화를 위한 언어 및 플랫폼 중립적인 확장 가능한 메커니즘을 제공하며, XML과 비슷하지만 더 작고 빠르며 단순합니다.

AAPT2 다운로드

Google Maven 저장소의 AAPT2 최신 버전을 사용하여 앱의 매니페스트 파일과 리소스 테이블을 protobuf 형식으로 생성할 수 있습니다.

Google의 Maven 저장소에서 AAPT2를 다운로드하려면 다음을 따르세요.

  1. 저장소 색인에서 com.android.tools.build > aapt2로 이동합니다.
  2. AAPT2의 최신 버전의 이름을 복사합니다.
  3. 복사한 버전 이름을 다음 URL에 삽입하고 타겟 운영체제를 지정합니다. https://dl.google.com/dl/android/maven2/com/android/tools/build/aapt2/aapt2-version/aapt2-aapt2-version-[windows | linux | osx].jar

    예를 들어 Windows용 버전 3.2.0-alpha18-4804415를 다운로드하려면 다음을 사용합니다. https://dl.google.com/dl/android/maven2/com/android/tools/build/aapt2/3.2.0-alpha18-4804415/aapt2-3.2.0-alpha18-4804415-windows.jar

  4. 브라우저에서 URL로 이동하면 AAPT2의 다운로드가 곧 시작됩니다.

  5. 방금 다운로드한 JAR 파일의 패키지를 해제합니다.

AAPT2에서 다음 명령을 사용하여 앱의 리소스를 컴파일합니다.

    aapt2 compile \
    project_root/module_root/src/main/res/drawable/Image1.png \
    project_root/module_root/src/main/res/drawable/Image2.png \
    -o compiled_resources/
    

AAPT2가 컴파일된 여러 리소스를 단일 APK에 연결하는 링크 단계에서는, 다음과 같이 --proto-format 플래그를 포함하여 앱의 매니페스트 및 컴파일된 리소스를 protobuf 형식으로 변환하도록 AAPT2에 지시합니다.

    aapt2 link --proto-format -o output.apk \
    -I android_sdk/platforms/android_version/android.jar \
    --manifest project_root/module_root/src/main/AndroidManifest.xml \
    -R compiled_resources/*.flat \
    --auto-add-overlay
    

이제 출력 APK에서 protobuf 형식으로 콘텐츠를 추출할 수 있습니다(앱의 AndroidManifest.xml, resources.pb 및 기타 리소스 파일). 다음 섹션에서 설명하는 것처럼 App Bundle을 빌드하는 데 필요한 입력 bundletool을 준비할 때 이러한 파일이 필요합니다.

사전 컴파일된 코드 및 리소스의 패키지화

bundletool을 사용하여 App Bundle을 생성하려면 먼저 지정된 앱 모듈을 위한 컴파일된 코드와 리소스를 포함하는 ZIP 파일을 제공해야 합니다. 각 모듈의 ZIP 파일의 내용 및 구성은 Android App Bundle 형식의 내용 및 구성과 매우 유사합니다. 예를 들면, 앱의 기본 모듈용 base.zip 파일을 만들고 내용을 다음과 같이 구성해야 합니다.

파일 또는 디렉터리 설명
manifest/AndroidManifest.xml protobuf 형식의 모듈의 매니페스트.
dex/... 앱의 컴파일된 하나 이상의 DEX 파일이 포함된 디렉터리. 이러한 파일의 이름은 classes.dex, classes2.dex, classes3.dex 등과 같이 지정해야 합니다.
res/... 모든 기기 구성을 위한 protobuf 형식으로 된 모듈의 리소스를 포함합니다. 하위 디렉터리와 파일의 구성은 일반적인 APK와 유사해야 합니다.
root/..., assets/...lib/... 이러한 디렉터리는 Android App Bundle 형식 관련 섹션에서 설명한 내용과 동일합니다.
resources.pb protobuf 형식의 앱 리소스 테이블

앱의 각 모듈용 ZIP 파일을 준비했으면, 다음 섹션에서 설명한 대로 App Bundle 빌드를 위해 bundletool로 파일을 전달할 수 있습니다.

bundletool을 사용하여 App Bundle 빌드

App Bundle을 빌드하려면 다음과 같이 bundletool build-bundle 명령을 사용합니다.

    bundletool build-bundle --modules=base.zip --output=mybundle.aab
    

다음 표에서는 build-bundle 명령에 대한 플래그를 자세히 설명합니다.

플래그 설명
--modules=path-to-base.zip, path-to-module2.zip,path-to-module3.zip bundletool이 App Bundle을 빌드할 때 사용해야 하는 모듈 ZIP 파일의 목록을 지정합니다.
--output=path-to-output.aab 출력 *.aab 파일의 경로와 파일 이름을 지정합니다.
--config=path-to-BundleConfig.json 빌드 프로세스를 맞춤설정하는 데 사용할 수 있는 선택적 구성 파일의 경로를 지정합니다. 자세한 내용은 다운스트림 APK 생성 맞춤설정에 관한 섹션을 참조하세요.
--metadata-file=target-bundle-path:local-file-path App Bundle 내에 선택적 메타데이터 파일을 패키지화하도록 bundletool에 지시합니다. 도구 모음 또는 앱 스토어의 다른 단계에 도움이 될 수 있는 ProGuard 매핑 또는 앱 DEX 파일의 전체 목록과 같은 데이터를 포함하는 데 이 파일을 사용할 수 있습니다.

target-bundle-path는 메타데이터 파일을 패키지화할 App Bundle의 루트에 상대적인 경로를 지정하고, local-file-path는 로컬 메타데이터 파일 자체의 경로를 지정합니다.

다운스트림 APK 생성 맞춤설정

App Bundle에는 BundleConfig.pb 파일이 포함되어 있는데, 이 파일은 앱 스토어(예: Google Play)가 App Bundle로부터 APK를 생성하는 데 필요한 메타데이터를 제공합니다. bundletool은 사용자를 위해 이 파일을 만들지만, 사용자는 BundleConfig.json 파일에서 메타데이터의 일정 부분을 구성하고 bundletool build-bundle 명령으로 전달할 수 있습니다. bundletool은 나중에 각 App Bundle에 포함된 protobuf 버전을 사용하여 이 파일을 변환하고 병합합니다.

예를 들어, 사용 설정 또는 사용 중지할 구성 APK의 카테고리를 제어할 수 있습니다. BundleConfig.json 파일의 다음 예는 각각 다른 언어를 타겟팅하는 구성 APK를 사용 중지합니다. 즉, 모든 언어의 리소스가 각각의 개별 기반 또는 동적 기능 APK에 포함됩니다.

{
      "optimizations": {
        "splitsConfig": {
          "splitDimension": [{
            "value": "LANGUAGE",
            "negate": true
          }]
        }
      }
    }
    

BundleConfig.json 파일에서는 다음과 같이 glob 패턴을 사용하여, APK를 패키지화할 때 어떤 파일 형식을 비압축 상태로 둘지를 지정할 수 있습니다.

{
      "compression": {
        "uncompressedGlob": ["res/raw/**", "assets/**.uncompressed"]
      }
    }
    

기본적으로 bundletool은 앱의 기본 라이브러리(Android 6.0 이상) 및 리소스 테이블(resources.arsc)을 압축하지 않습니다. BundleConfig.json에서 무엇을 구성할 수 있는지를 전체적으로 알아보려면 Proto3 구문을 사용하여 작성된 bundletool config.proto 파일을 참조하세요.

App Bundle에서 앱 배포

App Bundle을 빌드하고 서명한 경우 bundletool을 사용하여 APK를 생성하고 기기에 배포합니다.

명령줄에서 앱에 서명

앱에 서명할 때는 Android 스튜디오를 사용하지 않아도 됩니다. 명령줄에서 앱에 서명할 수 있습니다. 이때 APK에는 apksigner를, App Bundle에는 jarsigner를 사용하면 됩니다. 또는 Gradle을 구성하여 빌드 중에 대신 서명하도록 해도 됩니다. 어떤 방법을 사용하든, 아래와 같이 keytool을 사용하여 먼저 비공개 키를 생성해야 합니다.

    keytool -genkey -v -keystore my-release-key.jks
    -keyalg RSA -keysize 2048 -validity 10000 -alias my-alias
    

위의 예제를 실행하면 키 저장소 및 키 비밀번호를 입력하고, 키의 '고유 이름' 필드를 작성하라는 메시지가 표시됩니다. 그런 다음 my-release-key.jks라는 파일로 키 저장소가 생성되어 현재 디렉터리에 저장됩니다(원할 경우 이동 가능). 키 저장소에는 10,000일 동안 유효한 단일 키가 포함됩니다.

이제 아래의 섹션에 나와 있는 대로, APK 또는 App Bundle에 직접 서명하거나 빌드 프로세스 중에 앱에 서명하도록 Gradle을 구성할 수 있습니다.

명령줄에서 직접 앱 서명

명령줄에서 App Bundle에 서명하려면 jarsigner를 사용할 수 있습니다. 대신 APK에 서명하려면 아래와 같이 zipalignapksigner를 사용해야 합니다.

  1. Android 스튜디오에서 View > Tool Windows > Terminal을 선택하여 명령줄을 열고 서명하지 않은 APK가 있는 디렉터리로 이동합니다.
  2. zipalign을 사용하여 서명되지 않은 APK를 정렬합니다.

        zipalign -v -p 4 my-app-unsigned.apk my-app-unsigned-aligned.apk
        

    zipalign은 압축되지 않은 모든 데이터가 파일 시작 부분에 맞게 특정 바이트 정렬이 적용된 상태로 시작되도록 합니다. 이를 통해 앱이 소비하는 RAM 용량이 줄어들 수 있습니다.

  3. apksigner를 사용하여 비공개 키로 APK에 서명합니다.

        apksigner sign --ks my-release-key.jks --out my-app-release.apk my-app-unsigned-aligned.apk
        

    위 예제에서는 단일 키 저장소 파일 my-release-key.jks에 저장되어 있는 비공개 키와 인증서로 서명한 후 서명된 APK를 my-app-release.apk에 출력합니다.

    apksigner 도구는 별도의 비공개 키 및 인증서 파일을 사용하는 APK 파일 서명, 여러 서명자를 사용하는 APK 서명 등 다른 서명 옵션을 지원합니다. 자세한 내용은 apksigner 참조 문서를 참조하세요.

    참고: apksigner 도구를 사용하려면 수정 버전 24.0.3 이상의 Android SDK 빌드 도구를 설치해야 합니다. SDK Manager를 사용하여 이 패키지를 업데이트할 수 있습니다.

  4. APK가 서명되었는지 확인합니다.

        apksigner verify my-app-release.apk
        

앱에 서명하도록 Gradle 구성

모듈 레벨 build.gradle 파일을 열고 storeFile, storePassword, keyAliaskeyPassword의 항목이 있는 signingConfigs {} 블록을 추가한 다음, 이 객체를 빌드 유형의 signingConfig 속성에 전달합니다. 예를 들면 다음과 같습니다.

android {
        ...
        defaultConfig { ... }
        signingConfigs {
            release {
                // You need to specify either an absolute path or include the
                // keystore file in the same directory as the build.gradle file.
                storeFile file("my-release-key.jks")
                storePassword "password"
                keyAlias "my-alias"
                keyPassword "password"
            }
        }
        buildTypes {
            release {
                signingConfig signingConfigs.release
                ...
            }
        }
    }
    

이제 사용자가 Gradle 작업을 호출하여 앱을 빌드하면, Gradle이 앱에 서명하고 zipalign을 실행합니다.

또한, 릴리스 빌드를 서명 키로 구성했으므로 해당 빌드 유형에 '설치' 작업을 이용할 수 있습니다. 따라서 installRelease 작업을 이용해 에뮬레이터 또는 기기에서 APK의 빌드, 정렬, 서명 및 설치를 모두 해결할 수 있습니다.

비공개 키로 서명한 앱은 배포할 준비가 다 되었지만, 우선 앱 게시 방법에 관한 자세한 정보를 읽고 Google Play 출시 체크리스트부터 검토해야 합니다.