명령줄에서 앱 빌드

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

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

  • Windows 명령어 셸: 
    gradlew task-name
  • Mac, Linux 또는 Windows PowerShell: 
    ./gradlew task-name

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

gradlew tasks

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

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

빌드 유형 정보

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

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

build.gradle.kts 파일에서 맞춤 빌드 유형을 정의하고 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 Emulator를 사용하려면 Android 스튜디오를 사용하여 AVD(Android Virtual Device)를 생성해야 합니다.

AVD가 생성되면 Android Emulator를 시작하여 다음과 같이 앱을 설치하세요.

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

    emulator -avd avd_name

    AVD 이름이 확실하지 않으면 emulator -list-avds를 실행합니다.

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

    APK가 개발자 프리뷰 SDK를 사용하여 빌드된 경우(targetSdkVersion이 숫자가 아닌 문자일 때) install 명령어에 -t 옵션을 포함하여 테스트 APK를 설치해야 합니다.

    adb install path/to/your_app.apk

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

자세한 내용은 Android Emulator에서 앱 실행을 참조하세요.

실제 기기에 앱 배포

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

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

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

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에 업로드하려면 먼저 앱의 서명 정보로 기본 모듈의 build.gradle.kts 파일을 구성해야 합니다. 자세한 내용은 Gradle을 구성하여 앱에 서명하는 방법에 관한 섹션을 참조하세요. 예를 들어 앱의 출시 버전을 빌드하면 Gradle에서 자동으로 App Bundle을 생성하고 개발자가 build.gradle.kts 파일에 제공한 서명 정보로 서명합니다.

대신 별도의 단계로 App Bundle에 서명하려면 jarsigner를 사용하여 명령줄에서 App Bundle에 서명하면 됩니다. 앱 번들을 빌드하는 명령어는 다음과 같습니다.

jarsigner -keystore pathToKeystore app-release.aab keyAlias

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

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

사전 컴파일된 코드 및 리소스 패키징

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 파일을 준비한 후 bundletool에 전달하여 다음 섹션에서 설명하는 대로 App Bundle을 빌드할 수 있습니다.

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 구문을 사용하여 작성된 bundletoolconfig.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에 대신 서명하려면 아래 설명된 대로 zipalign 및 apksigner를 사용해야 합니다.

  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 Manager를 사용하여 이 패키지를 업데이트할 수 있습니다.

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

    apksigner verify my-app-release.apk

앱에 서명하도록 Gradle 구성

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

Kotlin


android {
    ...
    defaultConfig { ... }
    signingConfigs {
        create("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 {
        getByName("release") {
            signingConfig = signingConfigs.getByName("release")
            ...
        }
    }
}

Groovy

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 출시 체크리스트를 검토해야 합니다.