Multiplatform Gradle DSL reference
The Kotlin Multiplatform Gradle plugin is a tool for creating Kotlin multiplatform projects. Here we provide a reference of its contents; use it as a reminder when writing Gradle build scripts for Kotlin multiplatform projects. Learn the concepts of Kotlin multiplatform projects, how to create and configure them.
Id and version
The fully qualified name of the Kotlin Multiplatform Gradle plugin is
org.jetbrains.kotlin.multiplatform. If you use the Kotlin Gradle DSL, you can apply the plugin with
kotlin(“multiplatform”). The plugin versions match the Kotlin release versions. The most recent version is 1.5.21.
kotlin is the top-level block for multiplatform project configuration in the Gradle build script. Inside
kotlin, you can write the following blocks:
|<targetName>||Declares a particular target of a project. The names of available targets are listed in the Targets section.|
|All targets of the project.|
|All predefined targets. Use this for configuring multiple predefined targets at once.|
|Configures predefined and declares custom source sets of the project.|
Target is a part of the build responsible for compiling, testing, and packaging a piece of software aimed for one of the supported platforms.
The targets of a multiplatform project are described in the corresponding blocks inside
kotlin, for example,
iosArm64. The complete list of available targets is the following:
|Java Virtual Machine|
|Android NDK on ARM (ARM32) platforms|
|Android NDK on ARM64 platforms|
|Android NDK on x86 platforms|
|Android NDK on x86_64 platforms|
|Apple iOS on ARM (ARM32) platforms (Apple iPhone 5 and earlier)|
|Apple iOS on ARM64 platforms (Apple iPhone 5s and newer)|
|Apple iOS 64-bit simulator|
|Apple watchOS on ARM (ARM32) platforms (Apple Watch Series 3 and earlier)|
|Apple watchOS on ARM64_32 platforms (Apple Watch Series 4 and newer)|
|Apple watchOS 32-bit simulator (watchOS 6.3 and earlier)|
|Apple watchOS 64-bit simulator (watchOS 7.0 and newer)|
|Apple tvOS on ARM64 platforms (Apple TV 4th generation and newer)|
|Apple tvOS simulator|
|Linux on ARM64 platforms, for example, Raspberry Pi|
|Linux on hard-float ARM (ARM32) platforms|
|Linux on MIPS platforms|
|Linux on little-endian MIPS (mipsel) platforms|
|Linux on x86_64 platforms|
|64-bit Microsoft Windows|
|32-bit Microsoft Windows|
Configuration of a target can include two parts:
Common configuration available for all targets.
Each target can have one or more compilations.
Common target configuration
In any target block, you can use the following declarations:
|Attributes used for disambiguating targets for a single platform.|
|The preset that the target has been created from, if any.|
|Designates the Kotlin platform of this target. Avaiable values: |
|The name of the task that builds the resulting artifacts of this target.|
|The components used to setup Gradle publications.|
In addition to common target configuration,
jvm targets have a specific function:
|Includes Java sources into the JVM target’s compilations.|
Use this function for projects that contain both Java and Kotlin source files. Note that the default source directories for Java sources don't follow the Java plugin's defaults. Instead, they are derived from the Kotlin source sets. For example, if the JVM target has the default name
jvm, the paths are
src/jvmMain/java (for production Java sources) and
src/jvmTest/java for test Java sources. Learn how to include Java sources in JVM compilations.
|Configuration of the browser target.|
|Configuration of the Node.js target.|
Learn more about configuring Kotlin/JS projects.
browser can contain the following configuration blocks:
|Configuration of test execution.|
|Configuration of project running.|
|Configuration of project bundling with Webpack.|
|Configuration of Dead Code Elimination.|
|Path to output files.|
nodejs can contain configurations of test and run tasks:
|Configuration of test execution.|
|Configuration of project running.|
For native targets, the following specific blocks are available:
|Configuration of binaries to produce.|
|Configuration of interop with C libraries.|
There are the following kinds of binaries:
For binaries configuration, the following parameters are available:
|The compilation from which the binary is built. By default, |
|Options passed to a system linker during binary building.|
|Custom base name for the output file. The final file name will be formed by adding system-dependent prefix and postfix to this base name.|
|The entry point function for executable binaries. By default, it's |
|Access to the output file.|
|Access to the link task.|
|Access to the run task for executable binaries. For targets other than |
|For Objective-C frameworks. Includes a static library instead of a dynamic one.|
Learn more about building native binaries.
cinterops is a collection of descriptions for interop with native libraries. To provide an interop with a library, add an entry to
cinterops and define its parameters:
|Package prefix for the generated Kotlin API.|
|Options to pass to the compiler by the cinterop tool.|
|Directories to look for headers.|
Learn more how to configure interop with native languages.
The Kotlin multiplatform plugin contains two specific functions for android targets. Two functions help you configure build variants:
|Specifies build variants to publish. Learn more about publishing Android libraries.|
|Publishes all build variants.|
Learn more about compilation for Android.
sourceSets block describes source sets of the project. A source set contains Kotlin source files that participate in compilations together, along with their resources, dependencies, and language settings.
Predefined source sets
Predefined source sets are set up automatically upon creation of a multiplatform project. Available predefined source sets are the following:
|Code and resources shared between all platforms. Available in all multiplatform projects. Used in all main compilations of a project.|
|Test code and resources shared between all platforms. Available in all multiplatform projects. Used in all test compilations of a project.|
|<targetName><compilationName>||Target-specific sources for a compilation. <targetName> is the name of a predefined target and <compilationName> is the name of a compilation for this target. Examples: |
With Kotlin Gradle DSL, the sections of predefined source sets should be marked
Learn more about source sets.
Custom source sets
Custom source sets are created by the project developers manually. To create a custom source set, add a section with its name inside the
sourceSets section. If using Kotlin Gradle DSL, mark custom source sets
Note that a newly created source set isn’t connected to other ones. To use it in the project’s compilations, connect it with other source sets.
Source set parameters
Configurations of source sets are stored inside the corresponding blocks of
sourceSets. A source set has the following parameters:
|Location of Kotlin source files inside the source set directory.|
|Location of resources inside the source set directory.|
|Connection with another source set.|
|Dependencies of the source set.|
|Language settings applied to the source set.|
A target can have one or more compilations, for example, for production or testing. There are predefined compilations that are added automatically upon target creation. You can additionally create custom compilations.
To refer to all or some particular compilations of a target, use the
compilations object collection. From
compilations, you can refer to a compilation by its name.
Learn more about configuring compilations.
Predefined compilations are created automatically for each target of a project except for Android targets. Available predefined compilations are the following:
|Compilation for production sources.|
|Compilation for tests.|
In addition to predefined compilations, you can create your own custom compilations. To create a custom compilation, add a new item into the
compilations collection. If using Kotlin Gradle DSL, mark custom compilations
Learn more about creating a custom compilation.
A compilation has the following parameters:
|The compilation’s default source set.|
|Source sets participating in the compilation.|
|Source sets participating in the compilation and their connections via |
|Compiler options applied to the compilation. For the list of available options, see Compiler options.|
|Gradle task for compiling Kotlin sources.|
|Name of |
|Name of the Gradle task for compiling all sources of a compilation.|
|The compilation output.|
|Compile-time dependency files (classpath) of the compilation.|
|Runtime dependency files (classpath) of the compilation.|
dependencies block of the source set declaration contains the dependencies of this source set.
Learn more about configuring dependencies.
There are four types of dependencies:
|Dependencies used in the API of the current module.|
|Dependencies used in the module but not exposed outside it.|
|Dependencies used only for compilation of the current module.|
|Dependencies available at runtime but not visible during compilation of any module.|
Additionally, source sets can depend on each other and form a hierarchy. In this case, the dependsOn() relation is used.
Source set dependencies can also be declared in the top-level
dependencies block of the build script. In this case, their declarations follow the pattern
<sourceSetName><DependencyKind>, for example,
languageSettings block of a source set defines certain aspects of project analysis and build. The following language settings are available:
|Provides source compatibility with the specified version of Kotlin.|
|Allows using declarations only from the specified version of Kotlin bundled libraries.|
|Enables the specified language feature. The available values correspond to the language features that are currently experimental or have been introduced as such at some point.|
|Allows using the specified opt-in annotation.|
|Enables the progressive mode.|