Google is committed to advancing racial equity for Black communities. See how.

CommonExtension

@Incubating interface CommonExtension<AndroidSourceSetT : AndroidSourceSet, BuildFeaturesT : BuildFeatures, BuildTypeT : BuildType, DefaultConfigT : DefaultConfig, ProductFlavorT : ProductFlavor, SigningConfigT : SigningConfig, VariantT : Variant<VariantPropertiesT>, VariantPropertiesT : VariantProperties>
com.android.build.api.dsl.CommonExtension

Common extension properties for the Android Application. Library and Dynamic Feature Plugins.

Only the Android Gradle Plugin should create instances of this interface.

Summary

Public methods

abstract Unit
aaptOptions(action: AaptOptions.() -> Unit)

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

abstract Unit
adbOptions(action: AdbOptions.() -> Unit)

Specifies options for the Android Debug Bridge (ADB), such as APK installation options.

abstract Unit
buildFeatures(action: BuildFeaturesT.() -> Unit)

A list of build features that can be enabled or disabled on the Android Project.

abstract Unit
buildTypes(action: Action<in NamedDomainObjectContainer<BuildTypeT>>)

Encapsulates all build type configurations for this project.

abstract Unit

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

abstract Unit
compileSdkAddon(vendor: String, name: String, version: Int)

abstract Unit

abstract Unit
dataBinding(action: DataBinding.() -> Unit)

Specifies options for the Data Binding Library.

abstract Unit
defaultConfig(action: Action<DefaultConfigT>)

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

abstract Unit

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

abstract Unit
jacoco(action: JacocoOptions.() -> Unit)

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

abstract Unit
lintOptions(action: LintOptions.() -> Unit)

Specifies options for the lint tool.

abstract Unit
onVariantProperties(action: Action<VariantPropertiesT>)

Adds an Action to be performed on all VariantPropertiesT objects associated with this module

abstract Unit
onVariantProperties(action: VariantPropertiesT.() -> Unit)

Adds a lambda function to be performed on all VariantPropertiesT objects associated with this module.

abstract Unit
onVariants(action: Action<VariantT>)

Adds an Action to be performed on all VariantT objects associated with this module

abstract Unit
onVariants(action: VariantT.() -> Unit)

Adds a lambda function to be performed on all VariantT objects associated with this module

abstract Unit

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

abstract Unit

Encapsulates all product flavors configurations for this project.

abstract Unit

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

abstract Unit
sourceSets(action: NamedDomainObjectContainer<AndroidSourceSetT>.() -> Unit)

Encapsulates source set configurations for all variants.

abstract Unit
splits(action: Splits.() -> Unit)

Specifies configurations for building multiple APKs or APK splits.

abstract Unit
testOptions(action: TestOptions.() -> Unit)

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

abstract Unit

Includes the specified library to the classpath.

abstract Unit
useLibrary(name: String, required: Boolean)

Includes the specified library to the classpath.

Properties

abstract AaptOptions

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

abstract AdbOptions

Specifies options for the Android Debug Bridge (ADB), such as APK installation options.

abstract BuildFeaturesT

A list of build features that can be enabled or disabled on the Android Project.

abstract String

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

abstract NamedDomainObjectContainer<BuildTypeT>

Encapsulates all build type configurations for this project.

abstract CompileOptions

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

abstract Int?

Specifies the API level to compile your project against.

abstract String?

abstract ComposeOptions

abstract DataBinding

Specifies options for the Data Binding Library.

abstract DefaultConfigT

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

abstract ExternalNativeBuild

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

abstract MutableList<String>

Specifies the names of product flavor dimensions for this project.

abstract JacocoOptions

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

abstract LintOptions

Specifies options for the lint tool.

abstract String?

Requires the specified path to NDK be used.

abstract String?

Requires the specified NDK version to be used.

abstract GenericFilteredComponentActionRegistrar<VariantPropertiesT>

A registrar to apply actions on subsets of VariantPropertiesT via filters.

abstract GenericFilteredComponentActionRegistrar<VariantT>

A registrar to apply actions on subsets of VariantT via filters.

abstract PackagingOptions

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

abstract NamedDomainObjectContainer<ProductFlavorT>

Encapsulates all product flavors configurations for this project.

abstract String?

Specifies this project's resource prefix to Android Studio for editor features, such as Lint checks.

abstract SdkComponents

abstract NamedDomainObjectContainer<SigningConfigT>

Encapsulates signing configurations that you can apply to [ ] and [ ] configurations.

abstract NamedDomainObjectContainer<AndroidSourceSetT>

Encapsulates source set configurations for all variants.

abstract Splits

Specifies configurations for building multiple APKs or APK splits.

abstract TestOptions

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

Public methods

aaptOptions

abstract fun aaptOptions(action: AaptOptions.() -> Unit): Unit

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

For more information about the properties you can configure in this block, see AaptOptions.

adbOptions

abstract fun adbOptions(action: AdbOptions.() -> Unit): Unit

Specifies options for the Android Debug Bridge (ADB), such as APK installation options.

For more information about the properties you can configure in this block, see AdbOptions.

buildFeatures

abstract fun buildFeatures(action: BuildFeaturesT.() -> Unit): Unit

A list of build features that can be enabled or disabled on the Android Project.

buildTypes

abstract fun buildTypes(action: Action<in NamedDomainObjectContainer<BuildTypeT>>): Unit

Encapsulates all build type configurations for this project.

For more information about the properties you can configure in this block, see BuildType

compileOptions

abstract fun compileOptions(action: CompileOptions.() -> Unit): Unit

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

For more information about the properties you can configure in this block, see CompileOptions.

compileSdkAddon

abstract fun compileSdkAddon(
    vendor: String,
    name: String,
    version: Int
): Unit

composeOptions

abstract fun composeOptions(action: ComposeOptions.() -> Unit): Unit

dataBinding

abstract fun dataBinding(action: DataBinding.() -> Unit): Unit

Specifies options for the Data Binding Library.

For more information about the properties you can configure in this block, see DataBinding

defaultConfig

abstract fun defaultConfig(action: Action<DefaultConfigT>): Unit

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

You can override any defaultConfig property when configuring product flavors

For more information about the properties you can configure in this block, see DefaultConfig.

externalNativeBuild

abstract fun externalNativeBuild(action: ExternalNativeBuild.() -> Unit): Unit

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.

jacoco

abstract fun jacoco(action: JacocoOptions.() -> Unit): Unit

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>"
    }
}

lintOptions

abstract fun lintOptions(action: LintOptions.() -> Unit): Unit

Specifies options for the lint tool.

For more information about the properties you can configure in this block, see LintOptions.

onVariantProperties

abstract fun onVariantProperties(action: Action<VariantPropertiesT>): Unit

Adds an Action to be performed on all VariantPropertiesT objects associated with this module

This method is a shortcut for calling onVariants followed by Variant.onProperties.

Parameters
action: Action<VariantPropertiesT> a lambda taking a VariantProperties as a parameter.

onVariantProperties

abstract fun onVariantProperties(action: VariantPropertiesT.() -> Unit): Unit

Adds a lambda function to be performed on all VariantPropertiesT objects associated with this module.

This method is a shortcut for calling onVariants followed by Variant.onProperties.

Parameters
action: VariantPropertiesT.() -> Unit a lambda taking a VariantProperties as a parameter.

onVariants

abstract fun onVariants(action: Action<VariantT>): Unit

Adds an Action to be performed on all VariantT objects associated with this module

onVariants

abstract fun onVariants(action: VariantT.() -> Unit): Unit

Adds a lambda function to be performed on all VariantT objects associated with this module

packagingOptions

abstract fun packagingOptions(action: PackagingOptions.() -> Unit): Unit

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

For more information about the properties you can configure in this block, see PackagingOptions.

productFlavors

abstract fun productFlavors(action: Action<NamedDomainObjectContainer<ProductFlavorT>>): Unit

Encapsulates all product flavors configurations for this project.

For more information about the properties you can configure in this block, see ProductFlavor

signingConfigs

abstract fun signingConfigs(action: Action<NamedDomainObjectContainer<SigningConfigT>>): Unit

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

For more information about the properties you can configure in this block, see SigningConfig.

sourceSets

abstract fun sourceSets(action: NamedDomainObjectContainer<AndroidSourceSetT>.() -> Unit): Unit

Encapsulates source set configurations for all variants.

Note that the Android plugin uses its own implementation of source sets. For more information about the properties you can configure in this block, see AndroidSourceSet.

splits

abstract fun splits(action: Splits.() -> Unit): Unit

Specifies configurations for building multiple APKs or APK splits.

For more information about the properties you can configure in this block, see Splits.

testOptions

abstract fun testOptions(action: TestOptions.() -> Unit): Unit

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

For more information about the properties you can configure in this block, see TestOptions.

useLibrary

abstract fun useLibrary(name: String): Unit

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.

Parameters
name: String the name of the library.

useLibrary

abstract fun useLibrary(
    name: String,
    required: Boolean
): Unit

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

Parameters
name: String the name of the library.
required: Boolean if using the library requires a manifest entry, the entry will indicate that the library is not required.

Properties

aaptOptions

abstract val aaptOptions: AaptOptions

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

For more information about the properties you can configure in this block, see AaptOptions.

adbOptions

abstract val adbOptions: AdbOptions

Specifies options for the Android Debug Bridge (ADB), such as APK installation options.

For more information about the properties you can configure in this block, see AdbOptions.

buildFeatures

abstract val buildFeatures: BuildFeaturesT

A list of build features that can be enabled or disabled on the Android Project.

buildToolsVersion

abstract var buildToolsVersion: String

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:

android {
    // Specifying this property is optional.
    buildToolsVersion "26.0.0"
}

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.

buildTypes

abstract val buildTypes: NamedDomainObjectContainer<BuildTypeT>

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

abstract val compileOptions: CompileOptions

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

For more information about the properties you can configure in this block, see CompileOptions.

compileSdk

abstract var compileSdk: Int?

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: compileSdk 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.

compileSdkPreview

abstract var compileSdkPreview: String?

composeOptions

abstract val composeOptions: ComposeOptions

dataBinding

abstract val dataBinding: DataBinding

Specifies options for the Data Binding Library.

For more information about the properties you can configure in this block, see DataBinding

defaultConfig

abstract val defaultConfig: DefaultConfigT

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

You can override any defaultConfig property when configuring product flavors

For more information about the properties you can configure in this block, see DefaultConfig.

externalNativeBuild

abstract val 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.

flavorDimensions

abstract val flavorDimensions: MutableList<String>

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 combine 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.

jacoco

abstract val jacoco: JacocoOptions

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>"
    }
}

lintOptions

abstract val lintOptions: LintOptions

Specifies options for the lint tool.

For more information about the properties you can configure in this block, see LintOptions.

ndkPath

abstract var ndkPath: String?

Requires the specified path to NDK be used.

Use this to specify a path to the NDK folder to be used for C and C++ builds.

android {
    // Path to custom NDK location
    ndkPath '/path/to/ndk'
}

If this field is specified then android.ndkVersion may not be specified.

For additional information about NDK installation see Install and configure the NDK.

ndkVersion

abstract var ndkVersion: String?

Requires the specified NDK version to be used.

Use this to specify a fixed NDK version. Without this, each new version of the Android Gradle Plugin will choose a specific version of NDK to use, so upgrading the plugin also means upgrading the NDK. Locking to a specific version can increase repeatability of the build.

android {
    // Use a fixed NDK version
    ndkVersion '20.1.5948944'
}

If this field is specified then android.ndkPath may not be specified.

The required format of the version is major.minor.build. It's not legal to specify less precision. If ndk.dir is specified in local.properties file then the NDK that it points to must match the android.ndkVersion.

Prior to Android Gradle Plugin version 3.5, the highest installed version of NDK will be used. In Android Gradle Plugin 3.4, specifying android.ndkVersion was not an error, but the value would be ignored. Prior to Android Gradle Plugin version 3.4, it was illegal to specify android.ndkVersion.

For additional information about NDK installation see Install and configure the NDK.

onVariantProperties

abstract val onVariantProperties: GenericFilteredComponentActionRegistrar<VariantPropertiesT>

A registrar to apply actions on subsets of VariantPropertiesT via filters.

onVariants

abstract val onVariants: GenericFilteredComponentActionRegistrar<VariantT>

A registrar to apply actions on subsets of VariantT via filters.

Return
a GenericFilteredComponentActionRegistrar of VariantT

packagingOptions

abstract val packagingOptions: PackagingOptions

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

For more information about the properties you can configure in this block, see PackagingOptions.

productFlavors

abstract val productFlavors: NamedDomainObjectContainer<ProductFlavorT>

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 project'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 an 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 aflavorDimensionvalue. 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.

See Also

resourcePrefix

abstract var resourcePrefix: String?

Specifies this project'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 project resources helps avoid naming collisions with resources from other projects.

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 project resources:

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

sdkComponents

abstract val sdkComponents: SdkComponents

signingConfigs

abstract val signingConfigs: NamedDomainObjectContainer<SigningConfigT>

Encapsulates signing configurations that you can apply to [ ] and [ ] 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.

See Also

sourceSets

abstract val sourceSets: NamedDomainObjectContainer<AndroidSourceSetT>

Encapsulates source set configurations for all variants.

Note that the Android plugin uses its own implementation of source sets. For more information about the properties you can configure in this block, see AndroidSourceSet.

splits

abstract val splits: Splits

Specifies configurations for building multiple APKs or APK splits.

For more information about the properties you can configure in this block, see Splits.

testOptions

abstract val testOptions: TestOptions

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

For more information about the properties you can configure in this block, see TestOptions.