LibraryExtension

The android extension for com.android.library projects.

Apply this plugin to your project to create an Android library.

Properties

PropertyDescription
aaptOptions

Specifies options for the Android Asset Packaging Tool (AAPT).

adbExecutable

Returns a path to the Android Debug Bridge (ADB) executable from the Android SDK.

adbOptions

Specifies APK install options for the Android Debug Bridge (ADB).

buildToolsVersion

Specifies the version of the SDK Build Tools to use when building your project.

buildTypes

Encapsulates all build type configurations for this project.

compileOptions

Specifies Java compiler options, such as the language level of the Java source code and generated bytecode.

compileSdkVersion

Specifies the API level to compile your project against. The Android plugin requires you to configure this property.

dataBinding

Specifies options for the Data Binding Library.

defaultConfig

Specifies defaults for variant properties that the Android plugin applies to all build variants.

defaultPublishConfig

Specifies the version of the module to publish externally. This property is generally useful only to library modules that you intend to publish to a remote repository, such as Maven.

dexOptions

Specifies options for the DEX tool, such as enabling library pre-dexing.

externalNativeBuild

Specifies options for external native build using CMake or ndk-build.

flavorDimensionList

Specifies the names of product flavor dimensions for this project.

generatePureSplits
Incubating

Specifies whether to build APK splits or multiple APKs from configurations in the Splits block.

jacoco
Deprecated

Configure JaCoCo version that is used for offline instrumentation and coverage report.

libraryVariants

Returns a collection of build variants that the library project includes.

lintOptions

Specifies options for the lint tool.

ndkDirectory

The path to the Android NDK that Gradle uses for this project.

packagingOptions

Specifies options and rules that determine which files the Android plugin packages into your APK.

productFlavors

Encapsulates all product flavors configurations for this project.

resourcePrefix

Specifies the module's resource prefix to Android Studio for editor features, such as Lint checks. This property is useful only when using Android Studio.

sdkDirectory

The path to the Android SDK that Gradle uses for this project.

signingConfigs

Encapsulates signing configurations that you can apply to BuildType and ProductFlavor configurations.

sourceSets

Encapsulates source set configurations for all variants.

splits

Specifies configurations for building multiple APKs or APK splits.

testBuildType

Specifies the build type that the plugin should use to test the module.

testOptions

Specifies options for how the Android plugin should run local and instrumented tests.

testVariants

Returns a collection of Android test build variants.

unitTestVariants

Returns a collection of Android unit test build variants.

variantFilter

Specifies variants the Android plugin should include or remove from your Gradle project.

Methods

MethodDescription
flavorDimensions(dimensions)

Specifies the names of product flavor dimensions for this project.

useLibrary(name)

Includes the specified library to the classpath.

useLibrary(name, required)

Includes the specified library to the classpath.

Script blocks

No script blocks

Property details

AaptOptions aaptOptions

Specifies options for the Android Asset Packaging Tool (AAPT).

File adbExecutable

Returns a path to the Android Debug Bridge (ADB) executable from the Android SDK.

AdbOptions adbOptions

Specifies APK install options for the Android Debug Bridge (ADB).

String buildToolsVersion

Specifies the version of the SDK Build Tools to use when building your project.

When using Android plugin 3.0.0 or later, configuring this property is optional. By default, the plugin uses the minimum version of the build tools required by the version of the plugin you're using. To specify a different version of the build tools for the plugin to use, specify the version as follows:

// Specifying this property is optional.
buildToolsVersion "<build-tools-version>"

For a list of build tools releases, read the release notes.

Note that the value assigned to this property is parsed and stored in a normalized form, so reading it back may give a slightly different result.

Encapsulates all build type configurations for this project.

Unlike using ProductFlavor to create different versions of your project that you expect to co-exist on a single device, build types determine how Gradle builds and packages each version of your project. Developers typically use them to configure projects for various stages of a development lifecycle. For example, when creating a new project from Android Studio, the Android plugin configures a 'debug' and 'release' build type for you. By default, the 'debug' build type enables debugging options and signs your APK with a generic debug keystore. Conversely, The 'release' build type strips out debug symbols and requires you to create a release key and keystore for your app. You can then combine build types with product flavors to create build variants.

CompileOptions compileOptions

Specifies Java compiler options, such as the language level of the Java source code and generated bytecode.

String compileSdkVersion

Specifies the API level to compile your project against. The Android plugin requires you to configure this property.

This means your code can use only the Android APIs included in that API level and lower. You can configure the compile sdk version by adding the following to the android block: compileSdkVersion 26.

You should generally use the most up-to-date API level available. If you are planning to also support older API levels, it's good practice to use the Lint tool to check if you are using APIs that are not available in earlier API levels.

The value you assign to this property is parsed and stored in a normalized form, so reading it back may return a slightly different value.

DataBindingOptions dataBinding

Specifies options for the Data Binding Library.

Data binding helps you write declarative layouts and minimize the glue code necessary to bind your application logic and layouts.

DefaultConfig defaultConfig

Specifies defaults for variant properties that the Android plugin applies to all build variants.

You can override any defaultConfig property when configuring product flavors.

String defaultPublishConfig

Specifies the version of the module to publish externally. This property is generally useful only to library modules that you intend to publish to a remote repository, such as Maven.

If you don't configure this property, the Android plugin publishes the release version of the module by default. If the module configures product flavors, you need to configure this property with the name of the variant you want the plugin to publish, as shown below:

// Specifies the 'demoDebug' build variant as the default variant
// that the plugin should publish to external consumers.
defaultPublishConfig 'demoDebug'

If you plan to only consume your library module locally, you do not need to configure this property. Android plugin 3.0.0 and higher use variant-aware dependency resolution to automatically match the variant of the producer to that of the consumer. That is, when publishing a module to another local module, the plugin no longer respects this property when determining which version of the module to publish to the consumer.

DexOptions dexOptions

Specifies options for the DEX tool, such as enabling library pre-dexing.

Experimenting with DEX options tailored for your workstation may improve build performance. To learn more, read Optimize your build.

ExternalNativeBuild externalNativeBuild

Specifies options for external native build using CMake or ndk-build.

When using Android Studio 2.2 or higher with Android plugin 2.2.0 or higher, you can compile C and C++ code into a native library that Gradle packages into your APK.

To learn more, read Add C and C++ Code to Your Project.

List<String> flavorDimensionList

Specifies the names of product flavor dimensions for this project.

To configure flavor dimensions, use flavorDimensions. To learn more, read combine multiple product flavors.

boolean generatePureSplits

Note: This property is incubating and may change in a future version of the plugin.

Specifies whether to build APK splits or multiple APKs from configurations in the Splits block.

When you set this property to true, the Android plugin generates each object in the Splits block as a portion of a whole APK, called an APK split. Compared to building multiple APKs, each APK split includes only the components that each ABI or screen density requires. Generating APK splits is an incubating feature, which requires you to set BaseFlavor.minSdkVersion() to 21 or higher, and is currently supported only when publishing Android Instant Apps.

When you do not configure this property or set it to false (default), the Android plugin builds separate APKs for each object you configure in the Splits block that you can deploy to a device. To learn more about building different versions of your app that each target a different Application Binary Interfaces or screen density, read Build Multiple APKs.

Note: This property is deprecated and will be removed in a future version of the plugin.

Configure JaCoCo version that is used for offline instrumentation and coverage report.

To specify the version of JaCoCo you want to use, add the following to build.gradle file:

android {
    jacoco {
        version "<jacoco-version>"
    }
}

DefaultDomainObjectSet<LibraryVariant> libraryVariants

Returns a collection of build variants that the library project includes.

To process elements in this collection, you should use the all iterator. That's because the plugin populates this collection only after the project is evaluated. Unlike the each iterator, using all processes future elements as the plugin creates them.

The following sample iterates through all libraryVariants elements to inject a build variable into the manifest:

android.libraryVariants.all { variant ->
    def mergedFlavor = variant.getMergedFlavor()
    // Defines the value of a build variable you can use in the manifest.
    mergedFlavor.manifestPlaceholders = [hostName:"www.example.com"]
}

LintOptions lintOptions

Specifies options for the lint tool.

Android Studio and the Android SDK provide a code scanning tool called lint that can help you to identify and correct problems with the structural quality of your code without having to execute the app or write test cases. Each problem the tool detects is reported with a description message and a severity level, so that you can quickly prioritize the critical improvements that need to be made.

This property allows you to configure certain lint options, such as which checks to run or ignore. If you're using Android Studio, you can configure similar lint options from the IDE. To learn more about using and running lint, read Improve Your Code with Lint.

File ndkDirectory

The path to the Android NDK that Gradle uses for this project.

You can install the Android NDK by either using the SDK manager or downloading the standalone NDK package.

PackagingOptions packagingOptions

Specifies options and rules that determine which files the Android plugin packages into your APK.

For example, the following example tells the plugin to avoid packaging files that are intended only for testing:

packagingOptions {
    // Tells the plugin to not include any files in the 'testing-data/' directory,
    // which is specified as an absolute path from the root of the APK archive.
    // The exclude property includes certain defaults paths to help you avoid common
    // duplicate file errors when building projects with multiple dependencies.
    exclude "/testing-data/**"
}

To learn more about how to specify rules for packaging, merging, and excluding files, see PackagingOptions

Encapsulates all product flavors configurations for this project.

Product flavors represent different versions of your project that you expect to co-exist on a single device, the Google Play store, or repository. For example, you can configure 'demo' and 'full' product flavors for your app, and each of those flavors can specify different features, device requirements, resources, and application ID's--while sharing common source code and resources. So, product flavors allow you to output different versions of your project by simply changing only the components and settings that are different between them.

Configuring product flavors is similar to configuring build types: add them to the productFlavors block of your module's build.gradle file and configure the settings you want. Product flavors support the same properties as the DefaultConfig block--this is because defaultConfig defines a ProductFlavor object that the plugin uses as the base configuration for all other flavors. Each flavor you configure can then override any of the default values in defaultConfig, such as the applicationId.

When using Android plugin 3.0.0 and higher, each flavor must belong to a flavorDimensions value. By default, when you specify only one dimension, all flavors you configure belong to that dimension. If you specify more than one flavor dimension, you need to manually assign each flavor to a dimension. To learn more, read Use Flavor Dimensions for variant-aware dependency management.

When you configure product flavors, the Android plugin automatically combines them with your BuildType configurations to create build variants. If the plugin creates certain build variants that you don't want, you can filter variants.

String resourcePrefix

Specifies the module's resource prefix to Android Studio for editor features, such as Lint checks. This property is useful only when using Android Studio.

Including unique prefixes for module resources helps avoid naming collisions with resources from other modules. For example, when creating a library with String resources, you may want to name each resource with a unique prefix, such as "mylib_" to avoid naming collisions with similar resources that the consumer defines. You can then specify this prefix, as shown below, so that Android Studio expects this prefix when you name module resources:

// This property is useful only when developing your project in Android Studio.
resourcePrefix 'mylib_'

File sdkDirectory

The path to the Android SDK that Gradle uses for this project.

To learn more about downloading and installing the Android SDK, read Update Your Tools with the SDK Manager.

Encapsulates signing configurations that you can apply to BuildType and ProductFlavor configurations.

Android requires that all APKs be digitally signed with a certificate before they can be installed onto a device. When deploying a debug version of your project from Android Studio, the Android plugin automatically signs your APK with a generic debug certificate. However, to build an APK for release, you must sign the APK with a release key and keystore. You can do this by either using the Android Studio UI or manually configuring your build.gradle file.

Encapsulates source set configurations for all variants.

The Android plugin looks for your project's source code and resources in groups of directories called source sets. Each source set also determines the scope of build outputs that should consume its code and resources. For example, when creating a new project from Android Studio, the IDE creates directories for a main/ source set that contains the code and resources you want to share between all your build variants.

You can then define basic functionality in the main/ source set, but use product flavor source sets to change only the branding of your app between different clients, or include special permissions and logging functionality to only "debug" versions of your app.

The Android plugin expects you to organize files for source set directories a certain way, similar to the main/ source set. For example, Gradle expects Java class files that are specific to your "debug" build type to be located in the src/debug/java/ directory.

Gradle provides a useful task to shows you how to organize your files for each build type-, product flavor-, and build variant-specific source set. you can run this task from the command line as follows:

./gradlew sourceSets

The following sample output describes where Gradle expects to find certain files for the "debug" build type:

------------------------------------------------------------
Project :app
------------------------------------------------------------

...

debug
----
Compile configuration: compile
build.gradle name: android.sourceSets.debug
Java sources: [app/src/debug/java]
Manifest file: app/src/debug/AndroidManifest.xml
Android resources: [app/src/debug/res]
Assets: [app/src/debug/assets]
AIDL sources: [app/src/debug/aidl]
RenderScript sources: [app/src/debug/rs]
JNI sources: [app/src/debug/jni]
JNI libraries: [app/src/debug/jniLibs]
Java-style resources: [app/src/debug/resources]

If you have sources that are not organized into the default source set directories that Gradle expects, as described in the sample output above, you can use the sourceSet block to change where Gradle looks to gather files for each component of a given source set. You don't need to relocate the files; you only need to provide Gradle with the path(s), relative to the module-level build.gradle file, where Gradle should expect to find files for each source set component.

Note: You should specify only static paths whenever possible. Specifying dynamic paths reduces build speed and consistency.

The following code sample maps sources from the app/other/ directory to certain components of the main source set and changes the root directory of the androidTest source set:

android {
  ...
  sourceSets {
    // Encapsulates configurations for the main source set.
    main {
        // Changes the directory for Java sources. The default directory is
        // 'src/main/java'.
        java.srcDirs = ['other/java']

        // If you list multiple directories, Gradle uses all of them to collect
        // sources. Because Gradle gives these directories equal priority, if
        // you define the same resource in more than one directory, you get an
        // error when merging resources. The default directory is 'src/main/res'.
        res.srcDirs = ['other/res1', 'other/res2']

        // Note: You should avoid specifying a directory which is a parent to one
        // or more other directories you specify. For example, avoid the following:
        // res.srcDirs = ['other/res1', 'other/res1/layouts', 'other/res1/strings']
        // You should specify either only the root 'other/res1' directory, or only the
        // nested 'other/res1/layouts' and 'other/res1/strings' directories.

        // For each source set, you can specify only one Android manifest.
        // By default, Android Studio creates a manifest for your main source
        // set in the src/main/ directory.
        manifest.srcFile 'other/AndroidManifest.xml'
        ...
    }

    // Create additional blocks to configure other source sets.
    androidTest {
        // If all the files for a source set are located under a single root
        // directory, you can specify that directory using the setRoot property.
        // When gathering sources for the source set, Gradle looks only in locations
        // relative to the root directory you specify. For example, after applying the
        // configuration below for the androidTest source set, Gradle looks for Java
        // sources only in the src/tests/java/ directory.
        setRoot 'src/tests'
        ...
    }
  }
}

Splits splits

Specifies configurations for building multiple APKs or APK splits.

To generate APK splits, you need to also set generatePureSplits to true. However, generating APK splits is an incubating feature, which requires you to set BaseFlavor.minSdkVersion() to 21 or higher, and is currently supported only when publishing Android Instant Apps.

String testBuildType

Specifies the build type that the plugin should use to test the module.

By default, the Android plugin uses the "debug" build type. This means that when you deploy your instrumented tests using gradlew connectedAndroidTest, it uses the code and resources from the module's "debug" build type to create the test APK. The plugin then deploys the "debug" version of both the module's APK and the test APK to a connected device, and runs your tests.

To change the test build type to something other than "debug", specify it as follows:

android {
    // Changes the test build type for instrumented tests to "stage".
    testBuildType "stage"
}

If your module configures product flavors, the plugin creates a test APK and deploys tests for each build variant that uses the test build type. For example, consider if your module configures "debug" and "release" build types, and "free" and "paid" product flavors. By default, when you run your instrumented tests using gradlew connectedAndroidTest, the plugin performs executes the following tasks:

  • connectedFreeDebugAndroidTest: builds and deploys a freeDebug test APK and module APK, and runs instrumented tests for that variant.
  • connectedPaidDebugAndroidTest: builds and deploys a paidDebug test APK and module APK, and runs instrumented tests for that variant.

To learn more, read Create instrumented test for a build variant.

Note: You can execute connected<BuildVariant>AndroidTest tasks only for build variants that use the test build type. So, by default, running connectedStageAndroidTest results in the following build error:

Task 'connectedStageAndroidTest' not found in root project

You can resolve this issue by changing the test build type to "stage".

TestOptions testOptions

Specifies options for how the Android plugin should run local and instrumented tests.

To learn more, read Configure Gradle test options.

DomainObjectSet<TestVariant> testVariants

Returns a collection of Android test build variants.

To process elements in this collection, you should use the all iterator. That's because the plugin populates this collection only after the project is evaluated. Unlike the each iterator, using all processes future elements as the plugin creates them.

To learn more about testing Android projects, read Test Your App.

DomainObjectSet<UnitTestVariant> unitTestVariants

Returns a collection of Android unit test build variants.

To process elements in this collection, you should use the all iterator. That's because the plugin populates this collection only after the project is evaluated. Unlike the each iterator, using all processes future elements as the plugin creates them.

To learn more about testing Android projects, read Test Your App.

Action<VariantFilter> variantFilter

Specifies variants the Android plugin should include or remove from your Gradle project.

By default, the Android plugin creates a build variant for every possible combination of the product flavors and build types that you configure, and adds them to your Gradle project. However, there may be certain build variants that either you do not need or do not make sense in the context of your project. You can remove certain build variant configurations by creating a variant filter in your module-level build.gradle file.

The following example tells the plugin to ignore all variants that combine the "dev" product flavor, which you can configure to optimize build speeds during development, and the "release" build type:

android {
    ...
    variantFilter { variant ->

        def buildTypeName = variant.buildType*.name
        def flavorName = variant.flavors*.name

        if (flavorName.contains("dev") && buildTypeName.contains("release")) {
            // Tells Gradle to ignore each variant that satisfies the conditions above.
            setIgnore(true)
        }
    }
}

During subsequent builds, Gradle ignores any build variants that meet the conditions you specify. If you're using Android Studio, those variants no longer appear in the drop down menu when you click Build > Select Build Variant from the menu bar.

Method details

void flavorDimensions(String... dimensions)

Specifies the names of product flavor dimensions for this project.

When configuring product flavors with Android plugin 3.0.0 and higher, you must specify at least one flavor dimension, using the flavorDimensions property, and then assign each flavor to a dimension. Otherwise, you will get the following build error:

Error:All flavors must now belong to a named flavor dimension.
The flavor 'flavor_name' is not assigned to a flavor dimension.

By default, when you specify only one dimension, all flavors you configure automatically belong to that dimension. If you specify more than one dimension, you need to manually assign each flavor to a dimension, as shown in the sample below.

Flavor dimensions allow you to create groups of product flavors that you can compine with flavors from other flavor dimensions. For example, you can have one dimension that includes a 'free' and 'paid' version of your app, and another dimension for flavors that support different API levels, such as 'minApi21' and 'minApi24'. The Android plugin can then combine flavors from these dimensions—including their settings, code, and resources—to create variants such as 'debugFreeMinApi21' and 'releasePaidMinApi24', and so on. The sample below shows you how to specify flavor dimensions and add product flavors to them.

android {
    ...
    // Specifies the flavor dimensions you want to use. The order in which you
    // list each dimension determines its priority, from highest to lowest,
    // when Gradle merges variant sources and configurations. You must assign
    // each product flavor you configure to one of the flavor dimensions.
    flavorDimensions 'api', 'version'

    productFlavors {
      demo {
        // Assigns this product flavor to the 'version' flavor dimension.
        dimension 'version'
        ...
    }

      full {
        dimension 'version'
        ...
      }

      minApi24 {
        // Assigns this flavor to the 'api' dimension.
        dimension 'api'
        minSdkVersion '24'
        versionNameSuffix "-minApi24"
        ...
      }

      minApi21 {
        dimension "api"
        minSdkVersion '21'
        versionNameSuffix "-minApi21"
        ...
      }
   }
}

To learn more, read Combine multiple flavors.

void useLibrary(String name)

Includes the specified library to the classpath.

You typically use this property to support optional platform libraries that ship with the Android SDK. The following sample adds the Apache HTTP API library to the project classpath:

android {
    // Adds a platform library that ships with the Android SDK.
    useLibrary 'org.apache.http.legacy'
}

To include libraries that do not ship with the SDK, such as local library modules or binaries from remote repositories, add the libraries as dependencies in the dependencies block. Note that Android plugin 3.0.0 and later introduce new dependency configurations. To learn more about Gradle dependencies, read Dependency Management Basics.

void useLibrary(String name, boolean required)

Includes the specified library to the classpath.

You typically use this property to support optional platform libraries that ship with the Android SDK. The following sample adds the Apache HTTP API library to the project classpath:

android {
    // Adds a platform library that ships with the Android SDK.
    useLibrary 'org.apache.http.legacy'
}

To include libraries that do not ship with the SDK, such as local library modules or binaries from remote repositories, add the libraries as dependencies in the dependencies block. Note that Android plugin 3.0.0 and later introduce new dependency configurations. To learn more about Gradle dependencies, read Dependency Management Basics.