명령줄에서 앱 빌드

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 설치 작업 중 하나를 사용하여 앱을 설치할 수 있습니다.

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

        adb install path/to/your_app.apk
        

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

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

물리적 기기에 앱 배포

기기에서 앱을 실행할 수 있으려면 먼저 기기에서 USB 디버깅을 사용해야 합니다. 이 옵션은 Settings > Developer options에서 찾을 수 있습니다.

참고: Android 4.2 이상의 버전에서는 기본적으로 Developer options가 숨겨져 있습니다. 이 옵션을 사용하려면 Settings > About phone으로 이동하여 Build number를 7번 탭합니다. 이전 화면으로 돌아가서 Developer options를 찾습니다.

기기를 설정하고 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로 변환하고 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 형식으로 manifest 및 리소스 생성

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

AAPT2 다운로드

Google Maven 저장소의 AAPT2 최신 버전을 사용하여 앱의 manifest 파일과 리소스 표를 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 플래그를 포함하여 앱의 manifest 및 컴파일된 리소스를 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 형식의 모듈의 manifest
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 파일을 포함하며 이 파일은 번들에서 APK를 생성할 때 Google Play와 같은 앱 스토어에 필요한 메타데이터를 제공합니다. 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 도구를 사용하려면 Android SDK 빌드 도구 버전 24.0.3 이상을 설치해야 합니다. SDK 관리자를 사용하여 이 패키지를 업데이트할 수 있습니다.

  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을 실행합니다.

또한 서명 키로 출시 빌드를 구성했으므로 이 빌드 유형에 'install' 작업을 사용할 수 있습니다. 따라서 installRelease 작업을 이용해 에뮬레이터 또는 기기에 출시 APK를 빌드, 정렬, 서명 및 설치할 수 있습니다.

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