Optimization for library authors

As a library author, you should make sure that app developers can easily incorporate your library into their app while maintaining a high quality end user experience. You should ensure that your library is compatible with Android optimization without additional setup—or document that the library might be inappropriate for usage on Android.

This documentation is targeted at developers of published libraries, but might also be useful for developers of internal library modules in a large, modularized app.

If you're an app developer and want to learn about optimizing your Android app, see Enable app optimization. To learn about which libraries are appropriate to use, see Choose libraries wisely.

Use codegen over reflection

When possible, use code generation (codegen) over reflection. Codegen and reflection are both common approaches to avoid boilerplate code when programming, but codegen is more compatible with an app optimizer like R8:

• With codegen, code is analyzed and modified during the build process. Because there aren't any major modifications after compile time, the optimizer knows what code is ultimately needed and what can be safely removed.
• With reflection, code is analyzed and manipulated at runtime. Because the code isn't really finalized until it executes, the optimizer doesn't know what code can be safely removed. It'll likely remove code that is used dynamically through reflection during runtime, which causes app crashes for users.

Many modern libraries use codegen instead of reflection. See KSP for a common entrypoint, used by Room, Dagger2, and many others.

When reflection is okay

If you must use reflection, you should only reflect into either of the following:

• Specific targeted types (specific interface implementers or subclasses)
• Code using a specific runtime annotation

Using reflection in this way limits the runtime cost, and enables writing targeted consumer keep rules.

This specific and targeted form of reflection is a pattern you can see across both the Android framework (for example when inflating activities, views, and drawables) and AndroidX libraries (for example when constructing WorkManager ListenableWorkers, or RoomDatabases). By contrast, the open ended reflection of Gson isn't appropriate for usage in Android apps.

Write consumer keep rules

Libraries should package "consumer" keep rules, which use the same format as app keep rules. These rules are bundled into library artifacts (AARs or JARs) and get consumed automatically during Android app optimization when the library is used.

Note: Avoid putting global settings like -dontobfuscate into consumer rules files, since they will affect all downstream app optimization.

AAR libraries

To add consumer rules for an AAR library, use the consumerProguardFiles option in the Android library module's build script. For more information, see our guidance on creating library modules.

Kotlin

android {
    defaultConfig {
        consumerProguardFiles("consumer-proguard-rules.pro")
    }
    ...
}

Groovy

android {
    defaultConfig {
        consumerProguardFiles 'consumer-proguard-rules.pro'
    }
    ...
}

JAR libraries

To bundle rules with your Kotlin/Java library that ships as a JAR, put your rules file in the final JAR's META-INF/proguard/ directory, with any filename. For example if your code in <libraryroot>/src/main/kotlin, put a consumer rules file at <libraryroot>/src/main/resources/META-INF/proguard/consumer-proguard-rules.pro and the rules will be bundled in the correct location in your output JAR.

Verify that the final JAR bundles rules correctly by checking that the rules are in the META-INF/proguard directory.

Optimize AAR library build (advanced)

Generally, you shouldn't optimize a library build directly because the possible optimizations at library build time are very limited. It's only during an application build, when a library is included as part of an application, that R8 can know how all the methods of the library are used, and which parameters are passed. As a library developer, you need to reason about multiple stages of optimization and keep behavior, both at library and app build time, before you optimize that library.

If you still want to optimize your library at build time this is supported by the Android Gradle Plugin.

Kotlin

android {
    buildTypes {
        release {
            isMinifyEnabled = true
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro"
            )
        }
        configureEach {
            consumerProguardFiles("consumer-rules.pro")
        }
    }
}

Groovy

android {
    buildTypes {
        release {
            minifyEnabled true
            proguardFiles
                getDefaultProguardFile('proguard-android-optimize.txt'),
                'proguard-rules.pro'
        }
        configureEach {
            consumerProguardFiles "consumer-rules.pro"
        }
    }
}

Note that the behavior of proguardFiles is very different from consumerProguardFiles:

• proguardFiles are used at build time, often together with getDefaultProguardFile("proguard-android-optimize.txt"), to define which part of your library should be kept during the library build. At a minimum, this is your public API.
• consumerProguardFiles by contrast are packaged into the library to affect what optimizations happen later, during the build of an app that consumes your library.

For example, if your library uses reflection to construct internal classes, you might need to define the keep rules both in proguardFiles and consumerProguardFiles.

If you use -repackageclasses in your library's build, repackage classes to a sub-package inside your library's package. For example, use -repackageclasses 'com.example.mylibrary.internal' instead of -repackageclasses 'internal'.

Support different R8 versions (advanced)

You can tailor rules to target specific versions of R8. This enables your library to work optimally in projects that use newer R8 versions, while allowing existing rules to continue to be used in projects with older R8 versions.

To specify targeted R8 rules, you need to include them in the META-INF/com.android.tools directory inside classes.jar of an AAR or in the META-INF/com.android.tools directory of a JAR.

In an AAR library:
    proguard.txt (legacy location, the file name must be "proguard.txt")
    classes.jar
    └── META-INF
        └── com.android.tools (location of targeted R8 rules)
            ├── r8-from-<X>-upto-<Y>/<R8-rule-files>
            └── ... (more directories with the same name format)

In a JAR library:
    META-INF
    ├── proguard/<ProGuard-rule-files> (legacy location)
    └── com.android.tools (location of targeted R8 rules)
        ├── r8-from-<X>-upto-<Y>/<R8-rule-files>
        └── ... (more directories with the same name format)

In the META-INF/com.android.tools directory, there can be multiple subdirectories with names in the form of r8-from-<X>-upto-<Y> to indicate which R8 versions the rules are written for. Each subdirectory can have one or more files containing the R8 rules, with any file names and extensions.

Note that the -from-<X> and -upto-<Y> parts are optional, the <Y> version is exclusive, and the version ranges are usually continuous but can also overlap.

For example, r8, r8-upto-8.0.0, r8-from-8.0.0-upto-8.2.0, and r8-from-8.2.0 are directory names representing a set of targeted R8 rules. The rules under the r8 directory can be used by any R8 versions. The rules under the r8-from-8.0.0-upto-8.2.0 directory can be used by R8 from version 8.0.0 up to but not including version 8.2.0.

The Android Gradle plugin uses that information to select all the rules that can be used by the current R8 version. If a library does not specify targeted R8 rules, the Android Gradle plugin will select the rules from the legacy locations (proguard.txt for an AAR or META-INF/proguard/<ProGuard-rule-files> for a JAR).