Skip to content

Most visited

Recently visited

navigation

64K 이상의 메서드로 앱 구성

Android 플랫폼이 계속 성장함에 따라 Android 앱의 크기도 따라서 증가합니다. 앱과 이 애플리케이션이 참조하는 라이브러리의 크기가 일정 크기에 도달하면, 앱이 Android 앱 빌드 아키텍처의 제한에 도달했음을 나타내는 빌드 오류가 발생합니다. 이전 버전의 빌드 시스템에서는 이 오류를 다음과 같이 보고합니다.

Conversion to Dalvik format failed:
Unable to execute dex: method ID not in [0, 0xffff]: 65536

그보다 최근의 Android 빌드 시스템 버전에서는 다른 오류를 표시하지만 이 오류는 동일한 문제를 나타내는 것입니다.

trouble writing output:
Too many field references: 131000; max is 65536.
You may try using --multi-dex option.

두 오류 모두 공통 숫자인 65,536을 표시합니다. 이 숫자는 단일 DEX(Dalvik Executable) 바이트코드 파일 내에서 코드가 호출할 수 있는 참조의 총 개수를 나타냅니다. 이 페이지에서는 multidex라는 앱 구성을 활성화하여 이 제한을 넘는 방법을 설명합니다. multidex는 앱이 다중 DEX 파일을 빌드하고 읽을 수 있게 해줍니다.

64K 참조 제한 정보

Android 앱(APK) 파일에는 DEX(Dalvik Executable) 파일 형식의 실행 가능 바이트코드 파일이 포함됩니다. Dalvik Executable 사양은 단일 DEX 파일 내에서 참조될 수 있는 메서드의 총 개수를 65,536으로 제한하며 여기에는 Android 프레임워크 메서드, 라이브러리 메서드, 여러분 코드에 있는 메서드가 포함됩니다. 컴퓨터 공학 측면에서 킬로, K는 1024(또는 2^10)를 나타냅니다. 65,536은 64 X 1024와 동일하며, 이 제한을 '64K 참조 제한'이라고 부릅니다.

Android 5.0 미만에서 multidex 지원

Android 5.0(API 레벨 21) 미만의 플랫폼 버전에서는 앱 코드 실행을 위해 Dalvik 런타임을 사용합니다. 기본적으로, Dalvik에서는 APK당 하나의 classes.dex 바이트코드 파일로 앱을 제한합니다. 이러한 제한을 해결하기 위해 multidex 지원 라이브러리를 사용할 수 있습니다. 앱의 기본 DEX 파일에 속하는 이 라이브러리는 추가적인 DEX 파일과 이 파일 내의 코드에 대한 액세스를 관리합니다.

참고: minSdkVersion 20 이하의 multidex용으로 프로젝트가 구성된 경우, Android 4.4(API 레벨 20) 이하가 실행 중인 대상 기기에 배포하면 Android Studio가 Instant Run을 비활성화합니다.

Android 5.0 이상에서 multidex 지원

Android 5.0(API 레벨 21) 이상에서는 ART라는 런타임을 사용합니다. 기본적으로 이 런타임은 APK 파일로부터 여러 개의 DEX 파일을 로드하는 것을 지원합니다. ART는 앱 설치 시에 사전 컴파일을 수행합니다. 이 때 classesN.dex 파일을 스캔하고, Android 기기가 실행할 수 있도록 이 파일을 단일 .oat 파일로 컴파일합니다. 그러므로 minSdkVersion이 21 이상이라면 multidex 지원 라이브러리가 필요 없습니다.

Android 5.0 런타임에 대한 자세한 내용은 ART 및 Dalvik를 참조하세요.

참고: Instant Run이 사용되는 중에 앱의 minSdkVersion이 21 이상으로 설정된 경우, Android Studio는 자동으로 앱을 multidex용으로 구성합니다. Instant Run은 디버그 버전의 앱에서만 작동하므로, 64K 제한을 피하기 위해서는 릴리스 빌드를 multidex용으로 구성해야 합니다.

64K 제한 피하기

64K개 이상의 메서드 참조를 사용하도록 앱을 구성하기 전에, 앱 코드가 호출하는 참조의 총 개수를 줄이는 단계를 먼저 수행해야 합니다. 이 개수에는 앱 코드나 포함된 라이브러리에 의해 정의된 메서드가 포함됩니다. 다음 전략은 DEX 참조 제한을 넘지 않도록 도와줍니다.

이 기법을 사용하면 multidex를 활성화할 필요가 없을 뿐만 아니라 APK의 전체 크기를 줄일 수 있습니다.

multidex용 앱 구성

multidex 구성을 사용하도록 앱 프로젝트를 설정하려면 앱이 지원하는 최소 Android 버전에 따라 앱 프로젝트에서 다음 내용을 변경해야 할 수 있습니다.

minSdkVersion이 21 이상으로 설정되어 있을 경우 아래와 같이 모듈 수준의 build.gradle 파일에서 multiDexEnabledtrue로 설정하기만 하면 됩니다.

android {
    defaultConfig {
        ...
        minSdkVersion 21 
        targetSdkVersion 26
        multiDexEnabled true
    }
    ...
}

그러나 minSdkVersion이 20 이하로 설정되어 있으면 다음과 같이 multidex 지원 라이브러리를 사용해야 합니다.

앱을 빌드할 때 Android 빌드 도구는 기본 DEX 파일(classes.dex)과 지원하는 DEX 파일(classes2.dex, classes3.dex 등)을 필요에 따라 구성합니다. 그 후 빌드 시스템이 모든 DEX 파일을 APK로 패키징합니다.

런타임에서 multidex API는 특수 클래스 로더를 사용하여 (기본 classes.dex 파일)에서만 검색하는 대신) 메서드에서 사용할 수 있는 모든 DEX 파일을 검색합니다.

multidex 지원 라이브러리의 제한사항

multidex 지원 라이브러리에는 몇 가지 알려진 제한사항이 있으며, 이 라이브러리를 앱 빌드 구성에 통합할 때 이러한 제한사항을 파악하고 테스트해야 합니다.

기본 DEX 파일에 필요한 클래스 선언

multidex 앱에서 각각의 DEX 파일을 빌드할 때 빌드 도구는 앱이 성공적으로 시작될 수 있도록 복잡한 의사결정 과정을 통해 기본 DEX 파일에 어떤 클래스가 필요한지 결정합니다. 시작 시 필요한 클래스가 기본 DEX 파일에 제공되지 않으면 앱이 java.lang.NoClassDefFoundError 오류와 함께 충돌을 일으킵니다.

빌드 도구는 앱 코드에서 직접 액세스하는 코드의 경로를 인식하므로 이 코드에 대해서는 충돌이 일어나서는 안 됩니다. 그러나 라이브러리가 복잡한 종속성을 사용할 때와 같이 코드 경로가 명확하지 않을 경우에 충돌이 일어날 수 있습니다. 예를 들어 코드가 네이티브 코드에서 자바 메서드 검사 또는 호출을 사용한다면 이 클래스는 기본 DEX 파일에 필요한 것으로 인식되지 않을 수 있습니다.

따라서 java.lang.NoClassDefFoundError를 수신한다면 빌드 유형에서 multiDexKeepFile 또는 multiDexKeepProguard 속성으로 클래스를 선언하여 기본 DEX 파일에 필요한 추가 클래스를 수동으로 지정해야 합니다. 클래스가 multiDexKeepFile 또는 multiDexKeepProguard 파일에서 매칭되면 이 클래스는 기본 DEX 파일에 추가됩니다.

multiDexKeepFile 속성

multiDexKeepFile에서 지정한 파일은 com/example/MyClass.class 형식으로 한 줄에 하나의 클래스를 포함해야 합니다. 예를 들어 다음과 같은 multidex-config.txt 파일을 생성할 수 있습니다.

com/example/MyClass.class
com/example/MyOtherClass.class

그리고 이 파일을 다음과 같은 빌드 유형에 대해 선언할 수 있습니다.

android {
    buildTypes {
        release {
            multiDexKeepFile file 'multidex-config.txt'
            ...
        }
    }
}

Gradle은 build.gradle 파일에 상대적인 경로를 읽으므로 위의 예시는 multidex-config.txtbuild.gradle 파일과 같은 디렉토리에 있을 때 유효합니다.

multiDexKeepProguard 속성

multiDexKeepProguard 파일은 Proguard와 같은 형식을 사용하고 전체 Proguard 문법을 지원합니다. Proguard 형식과 문법에 대한 자세한 내용은 Proguard 매뉴얼의 옵션 유지 섹션을 참조하세요.

multiDexKeepProguard에서 지정한 파일에는 유효한 ProGuard 구문으로 된 -keep 옵션이 포함되어야 합니다. 예를 들어 -keep com.example.MyClass.class와 같습니다. 다음과 같은 multidex-config.pro 파일을 생성할 수 있습니다.

-keep class com.example.MyClass
-keep class com.example.MyClassToo

패키지에서 모든 클래스를 지정하고 싶다면 파일은 다음과 같은 형식을 취해야 합니다.

-keep class com.example.** { *; } // All classes in the com.example package

그리고 이 파일을 다음과 같은 빌드 유형에 대해 선언할 수 있습니다.

android {
    buildTypes {
        release {
            multiDexKeepProguard 'multidex-config.pro'
            ...
        }
    }
}

개발 빌드에서 multidex 최적화

기본 DEX 파일에 어떤 클래스를 포함해야 하고 보조 DEX 파일에 어떤 클래스를 포함할 수 있는지에 관한 복잡한 결정을 빌드 시스템이 내려야 하기 때문에, multidex 구성에는 상당히 긴 빌드 처리 시간이 필요합니다. 일반적으로 multidex를 사용하는 증분 빌드는 시간이 더 오래 걸리고 개발 속도를 늦출 가능성이 있습니다.

multidex 출력 시 빌드 시간이 길어지는 것을 완화하기 위해서는 productFlavors를 사용하여 minSdkVersion 값이 다른 개발 버전과 릴리스 버전으로 두 개의 빌드 변형을 생성해야 합니다.

개발 버전은 minSdkVersion을 21로 설정합니다. 이 설정은 pre-dexing이라는 빌드 기능을 활성화합니다. 이 기능은 Android 5.0(API 레벨 21) 이상에서만 제공되는 ART 형식으로 multidex 출력을 더욱 빠르게 생성합니다. 릴리스 버전은 minSdkVersion을 실제 최소 지원 수준에 맞게 설정합니다. 이 설정은 더 많은 기기와 호환되는 multidex APK를 생성하지만, 빌드 시간이 더 오래 걸립니다.

다음 빌드 구성 샘플에서는 이러한 버전을 Gradle 빌드 파일에서 설정하는 방법을 보여줍니다.

android {
    defaultConfig {
        ...
        multiDexEnabled true
    }
    productFlavors {
        dev {
            // Enable pre-dexing to produce an APK that can be tested on
            // Android 5.0+ without the time-consuming DEX build processes.
            minSdkVersion 21
        }
        prod {
            // The actual minSdkVersion for the production version.
            minSdkVersion 14
        }
    }
    buildTypes {
        release {
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android.txt'),
                                                 'proguard-rules.pro'
        }
    }
}
dependencies {
    compile 'com.android.support:multidex:1.0.1'
}

이 구성 변경을 완료한 후에는 증분 빌드에 dev 제품 버전과 debug 빌드 유형의 특성을 결합한 앱의 devDebug 변형을 사용할 수 있습니다. 이렇게 하면 multidex가 활성화되고 proguard는 비활성화된 디버그 가능한 앱이 생성됩니다(minifyEnabled의 기본값이 false이기 때문입니다). 이 설정에서 Gradle용 Android 플러그인이 다음과 같이 동작합니다.

  1. pre-dexing 수행: 각 앱 모듈과 종속성을 별도 DEX 파일로 빌드합니다.
  2. 각 DEX 파일은 수정 없이 APK에 포함됩니다(코드 축소 없음).
  3. 무엇보다도 중요한 점은, 모듈 DEX 파일이 결합되지 않으므로 기본 DEX 파일의 내용을 결정하는 데 긴 시간이 걸리는 계산을 피할 수 있습니다.

이 설정에서는 수정된 모듈의 DEX 파일만이 다시 계산되어 이후 빌드에서 다시 패키징되기 때문에 신속한 증분 빌드가 가능합니다. 그러나 이 빌드에서 생성된 APK는 Android 5.0 기기에서 테스트를 수행할 때만 사용될 수 있습니다. 이 구성을 버전으로 구현하게 되면, 릴리스에 적합한 최소 API 수준과 proguard 코드 축소를 통해 정상적인 빌드를 수행할 수 있습니다.

또한 prodDebug 변형 빌드를 비롯한 다른 변형을 빌드할 수도 있습니다. 이 변형 빌드는 빌드 시간이 더 오래 걸리지만 개발 이외의 테스트에 사용될 수 있습니다. 표시된 구성 내에서 prodRelease 변형이 최종 테스트 및 릴리스 버전이 됩니다. 빌드 변형에 대한 자세한 내용은 빌드 변형 구성을 참조하세요.

팁: 여러 multidex 필요에 맞는 여러 가지 빌드 변형을 생성하였으므로 각 변형에 여러 가지 매니페스트 파일을 제공하거나(API 레벨이 20 이하인 빌드 변형만 <application> 태그 이름 변경) 각 변형에 다른 Application 서브클래스를 생성할 수 있습니다(API 레벨이 20 이하인 변형만 MultiDexApplication 클래스를 확장하거나 MultiDex.install(this) 호출).

multidex 앱 테스트

multidex 앱의 계측 테스트를 작성할 때는 추가 구성이 필요 없습니다. AndroidJUnitRunnerMultiDexApplication을 사용하거나 사용자설정 Application 객체에서 attachBaseContext() 메서드를 재정의하고 MultiDex.install(this)를 호출하여 multidex를 활성화할 경우 기본적으로 multidex를 지원합니다.

또는 AndroidJUnitRunner에서 onCreate() 메서드를 재정의할 수 있습니다.

public void onCreate(Bundle arguments) {
    MultiDex.install(getTargetContext());
    super.onCreate(arguments);
    ...
}

참고: multidex를 사용하여 테스트 APK를 생성하는 것은 현재 지원되지 않습니다.

This site uses cookies to store your preferences for site-specific language and display options.

Get the latest Android developer news and tips that will help you find success on Google Play.

* Required Fields

Hooray!

Browse this site in ?

You requested a page in , but your language preference for this site is .

Would you like to change your language preference and browse this site in ? If you want to change your language preference later, use the language menu at the bottom of each page.

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

Take a short survey?
Help us improve the Android developer experience.
(Sep 2017 survey)