KotlinMultiplatformAndroidExtension

@Incubating interface KotlinMultiplatformAndroidExtension


Extension properties for Kotlin multiplatform Android libraries.

Only the Kotlin Multiplatform Android Plugin should create instances of this interface.

Warning: this is an experimental API and will change in the near future, and you shouldn't publish plugins depending on it.

Summary

Public functions

@Incubating Unit

Options for configuring AAR metadata.

@Incubating Unit

Specifies options for doing variant selection for external Android dependencies based on build types and product flavours

@Incubating Unit

Specifies options for the lint tool.

@Incubating Unit

Specifies options for the R8/D8 optimization tool.

@Incubating Unit

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

@Incubating Unit

Includes the specified library to the classpath.

@Incubating Unit
useLibrary(name: String, required: Boolean)

Includes the specified library to the classpath.

@Incubating Unit

Creates and configures a compilation for tests that run on the device (previously referred to as instrumented tests).

@Incubating HasConfigurableValue<KotlinMultiplatformAndroidTestOnDevice>

Creates and configures a compilation for tests that run on the device (previously referred to as instrumented tests).

@Incubating Unit

Creates and configures a compilation for tests that run on the JVM (previously referred to as unit tests).

@Incubating HasConfigurableValue<KotlinMultiplatformAndroidTestOnJvm>

Creates and configures a compilation for tests that run on the JVM (previously referred to as unit tests).

Public properties

AarMetadata

Options for configuring AAR metadata.

String

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

Int?

Specifies the API level to compile your project against.

Int?
String?
DependencyVariantSelection

Specifies options for doing variant selection for external Android dependencies based on build types and product flavours

MutableMap<StringAny>

Additional per module experimental properties.

Boolean

Whether core library desugaring is enabled.

Lint

Specifies options for the lint tool.

Int?

The maxSdkVersion, or null if not specified.

Int?

The minimum SDK version.

String?
String?

The namespace of the generated R and BuildConfig classes.

KmpOptimization

Specifies options for the R8/D8 optimization tool.

Packaging

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

TestCoverage

Configure the gathering of code-coverage from tests.

String?

The namespace used by the android test and unit test components for the generated R and BuildConfig classes.

Public functions

aarMetadata

@Incubating
fun aarMetadata(action: @ExtensionFunctionType AarMetadata.() -> Unit): Unit

Options for configuring AAR metadata.

dependencyVariantSelection

@Incubating
fun dependencyVariantSelection(action: @ExtensionFunctionType DependencyVariantSelection.() -> Unit): Unit

Specifies options for doing variant selection for external Android dependencies based on build types and product flavours

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

lint

@Incubating
fun lint(action: @ExtensionFunctionType Lint.() -> Unit): Unit

Specifies options for the lint tool.

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

optimization

@Incubating
fun optimization(action: @ExtensionFunctionType KmpOptimization.() -> Unit): Unit

Specifies options for the R8/D8 optimization tool.

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

packaging

@Incubating
fun packaging(action: @ExtensionFunctionType Packaging.() -> 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 Packaging.

useLibrary

@Incubating
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

@Incubating
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, "https://developer.android.com/studio/build/dependencies.html 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.

withAndroidTestOnDevice

@Incubating
fun withAndroidTestOnDevice(action: @ExtensionFunctionType KotlinMultiplatformAndroidTestOnDevice.() -> Unit): Unit

Creates and configures a compilation for tests that run on the device (previously referred to as instrumented tests). Invoking this method will create a KotlinMultiplatformAndroidTestOnDeviceCompilation object with the following defaults:

  • compilation name is "testOnDevice"

  • default sourceSet name is "androidTestOnDevice" (sources would be located at $project/src/androidTestOnDevice)

  • sourceSet tree is null, which means that the commonTest sourceSet will not be included in the compilation.

Only a single compilation of this test type can be created. If you want to configure KotlinMultiplatformAndroidTestOnDevice options, you can modify it on the kotlin compilation as follows:

kotlin {
androidLibrary {
compilations.withType(com.android.build.api.dsl.KotlinMultiplatformAndroidTestOnDevice::class.java) {
// configure options
}
}
}

withAndroidTestOnDeviceBuilder

@Incubating
fun withAndroidTestOnDeviceBuilder(action: @ExtensionFunctionType KotlinMultiplatformAndroidCompilationBuilder.() -> Unit): HasConfigurableValue<KotlinMultiplatformAndroidTestOnDevice>

Creates and configures a compilation for tests that run on the device (previously referred to as instrumented tests). Invoking this method will create a KotlinMultiplatformAndroidTestOnDeviceCompilation object using the values set in the KotlinMultiplatformAndroidCompilationBuilder.

The returned object can be used to configure KotlinMultiplatformAndroidTestOnDevice as follows:

kotlin {
androidLibrary {
withAndroidTestOnDeviceBuilder {
compilationName = "instrumentedTest"
defaultSourceSetName = "androidInstrumentedTest"
}.configure {
instrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
}
}
}

Only a single compilation of this test type can be created. If you want to configure KotlinMultiplatformAndroidTestOnDevice options, you can modify it on the kotlin compilation as follows:

kotlin {
androidLibrary {
compilations.withType(com.android.build.api.dsl.KotlinMultiplatformAndroidTestOnDevice::class.java) {
// configure options
}
}
}

withAndroidTestOnJvm

@Incubating
fun withAndroidTestOnJvm(action: @ExtensionFunctionType KotlinMultiplatformAndroidTestOnJvm.() -> Unit): Unit

Creates and configures a compilation for tests that run on the JVM (previously referred to as unit tests). Invoking this method will create a KotlinMultiplatformAndroidTestOnJvmCompilation object with the following defaults (You can change these defaults by using withAndroidTestOnJvmBuilder instead):

  • compilation name is "testOnJvm"

  • default sourceSet name is "androidTestOnJvm" (sources would be located at $project/src/androidTestOnJvm)

  • sourceSet tree is test, which means that the commonTest sourceSet would be included in the compilation.

Only a single compilation of this test type can be created. If you want to configure KotlinMultiplatformAndroidTestOnJvm options, you can modify it on the kotlin compilation as follows:

kotlin {
androidLibrary {
compilations.withType(com.android.build.api.dsl.KotlinMultiplatformAndroidTestOnJvm::class.java) {
// configure options
}
}
}

withAndroidTestOnJvmBuilder

@Incubating
fun withAndroidTestOnJvmBuilder(action: @ExtensionFunctionType KotlinMultiplatformAndroidCompilationBuilder.() -> Unit): HasConfigurableValue<KotlinMultiplatformAndroidTestOnJvm>

Creates and configures a compilation for tests that run on the JVM (previously referred to as unit tests). Invoking this method will create a KotlinMultiplatformAndroidTestOnJvmCompilation object using the values set in the KotlinMultiplatformAndroidCompilationBuilder.

The returned object can be used to configure KotlinMultiplatformAndroidTestOnJvm as follows:

kotlin {
androidLibrary {
withAndroidTestOnJvmBuilder {
compilationName = "unitTest"
defaultSourceSetName = "androidUnitTest"
}.configure {
isIncludeAndroidResources = true
}
}
}

Only a single compilation of this test type can be created. If you want to configure KotlinMultiplatformAndroidTestOnJvm options, you can modify it on the kotlin compilation as follows:

kotlin {
androidLibrary {
compilations.withType(com.android.build.api.dsl.KotlinMultiplatformAndroidTestOnJvm::class.java) {
// configure options
}
}
}

Public properties

aarMetadata

val aarMetadataAarMetadata

Options for configuring AAR metadata.

buildToolsVersion

var buildToolsVersionString

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

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.

compileSdk

var compileSdkInt?

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.

compileSdkExtension

var compileSdkExtensionInt?

compileSdkPreview

var compileSdkPreviewString?

dependencyVariantSelection

val dependencyVariantSelectionDependencyVariantSelection

Specifies options for doing variant selection for external Android dependencies based on build types and product flavours

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

experimentalProperties

val experimentalPropertiesMutableMap<StringAny>

Additional per module experimental properties.

isCoreLibraryDesugaringEnabled

var isCoreLibraryDesugaringEnabledBoolean

Whether core library desugaring is enabled.

lint

val lintLint

Specifies options for the lint tool.

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

maxSdk

var maxSdkInt?

The maxSdkVersion, or null if not specified. This is only the value set on this produce flavor.

See uses-sdk element documentation.

minSdk

var minSdkInt?

The minimum SDK version. Setting this it will override previous calls of minSdk and minSdkPreview setters. Only one of minSdk and minSdkPreview should be set.

See uses-sdk element documentation.

minSdkPreview

var minSdkPreviewString?

namespace

var namespaceString?

The namespace of the generated R and BuildConfig classes. Also, the namespace used to resolve any relative class names that are declared in the AndroidManifest.xml.

optimization

val optimizationKmpOptimization

Specifies options for the R8/D8 optimization tool.

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

packaging

val packagingPackaging

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

testCoverage

val testCoverageTestCoverage

Configure the gathering of code-coverage from tests.

testNamespace

var testNamespaceString?

The namespace used by the android test and unit test components for the generated R and BuildConfig classes.