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 versionThe 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 2.2.0.
plugins { kotlin("multiplatform") version "2.2.0" }
plugins { id 'org.jetbrains.kotlin.multiplatform' version '2.2.0' }
Top-level blockskotlin {} is the top-level block for multiplatform project configuration in the Gradle build script. Inside kotlin {}, you can write the following blocks:
Block
Description
<targetName>
Declares a particular target of a project. The names of available targets are listed in the Targets section.
targets
Lists all targets of the project.
sourceSets
Configures predefined and declares custom source sets of the project.
compilerOptions
Specifies common extension-level compiler options that are used as defaults for all targets and shared source sets.
TargetsA target is a part of the build responsible for compiling, testing, and packaging a piece of software aimed at one of the supported platforms. Kotlin provides targets for each platform, so you can instruct Kotlin to compile code for that specific target. Learn more about setting up targets.
Each target can have one or more compilations. In addition to default compilations for test and production purposes, you can create custom compilations.
The targets of a multiplatform project are described in the corresponding blocks inside kotlin {}, for example, jvm, androidTarget, iosArm64. The complete list of available targets is the following:
Target platform
Target
Comments
Kotlin/JVM
jvm
Kotlin/Wasm
wasmJs
Use it if you plan to run your projects in the JavaScript runtime.
wasmWasi
Use it if you need support for the WASI system interface.
Kotlin/JS
js
Select the execution environment:
browser {} for applications running in the browser.
nodejs {} for applications running on Node.js.
Learn more in Setting up a Kotlin/JS project.
Kotlin/Native
Learn about currently supported targets for the macOS, Linux, and Windows hosts in Kotlin/Native target support.
Android applications and libraries
androidTarget
Manually apply an Android Gradle plugin: com.android.application or com.android.library.
You can only create one Android target per Gradle subproject.
A target that is not supported by the current host is ignored during building and, therefore, not published.
kotlin { jvm() iosArm64() macosX64() js().browser() }
The configuration of a target can include two parts:
Common configuration available for all targets.
Target-specific configuration.
Each target can have one or more compilations.
Common target configurationIn any target block, you can use the following declarations:
Name
Description
platformType
The Kotlin platform for this target. Available values: jvm, androidJvm, js, wasm, native, common.
artifactsTaskName
The name of the task that builds the resulting artifacts of this target.
components
Components used to set up Gradle publications.
compilerOptions
Compiler options used for the target. This declaration overrides any compilerOptions {} configured at top level.
The js {} block describes the configuration of Kotlin/JS targets, and the wasmJs {} block describes the configuration of Kotlin/Wasm targets interoperable with JavaScript. They can contain one of two blocks depending on the target execution environment:
Name
Description
Configuration of the browser target.
Configuration of the Node.js target.
Learn more about configuring Kotlin/JS projects.
A separate wasmWasi {} block describes the configuration of Kotlin/Wasm targets that support the WASI system interface. Here, only the nodejs execution environment is available:
kotlin { wasmWasi { nodejs() binaries.executable() } }
All the web targets, js, wasmJs, and wasmWasi, also support the binaries.executable() call. It explicitly instructs the Kotlin compiler to emit executable files. For more information, see Execution environments in the Kotlin/JS documentation.
browser {} can contain the following configuration blocks:
Name
Description
testRuns
Configuration of test execution.
runTask
Configuration of project running.
webpackTask
Configuration of project bundling with Webpack.
distribution
Path to output files.
kotlin { js().browser { webpackTask { /* ... */ } testRuns { /* ... */ } distribution { directory = File("$projectDir/customdir/") } } }
Node.jsnodejs {} can contain configurations of test and run tasks:
Name
Description
testRuns
Configuration of test execution.
runTask
Configuration of project running.
kotlin { js().nodejs { runTask { /* ... */ } testRuns { /* ... */ } } }
Native targetsFor native targets, the following specific blocks are available:
BinariesThere are the following kinds of binaries:
Name
Description
executable
Product executable.
test
Test executable.
sharedLib
Shared library.
staticLib
Static library.
framework
Objective-C framework.
kotlin { linuxX64 { // Use your target instead. binaries { executable { // Binary configuration. } } } }
For binary configuration, the following parameters are available:
Name
Description
compilation
The compilation from which the binary is built. By default, test binaries are based on the test compilation while other binaries - on the main compilation.
linkerOpts
Options passed to a system linker during binary building.
baseName
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.
entryPoint
The entry point function for executable binaries. By default, it's main() in the root package.
outputFile
Access to the output file.
linkTask
Access to the link task.
runTask
Access to the run task for executable binaries. For targets other than linuxX64, macosX64, or mingwX64 the value is null.
isStatic
For Objective-C frameworks. Includes a static library instead of a dynamic one.
binaries { executable("my_executable", listOf(RELEASE)) { // Build a binary on the basis of the test compilation. compilation = compilations["test"] // Custom command line options for the linker. linkerOpts = mutableListOf("-L/lib/search/path", "-L/another/search/path", "-lmylib") // Base name for the output file. baseName = "foo" // Custom entry point function. entryPoint = "org.example.main" // Accessing the output file. println("Executable path: ${outputFile.absolutePath}") // Accessing the link task. linkTask.dependsOn(additionalPreprocessingTask) // Accessing the run task. // Note that the runTask is null for non-host platforms. runTask?.dependsOn(prepareForRun) } framework("my_framework" listOf(RELEASE)) { // Include a static library instead of a dynamic one into the framework. isStatic = true } }
binaries { executable('my_executable', [RELEASE]) { // Build a binary on the basis of the test compilation. compilation = compilations.test // Custom command line options for the linker. linkerOpts = ['-L/lib/search/path', '-L/another/search/path', '-lmylib'] // Base name for the output file. baseName = 'foo' // Custom entry point function. entryPoint = 'org.example.main' // Accessing the output file. println("Executable path: ${outputFile.absolutePath}") // Accessing the link task. linkTask.dependsOn(additionalPreprocessingTask) // Accessing the run task. // Note that the runTask is null for non-host platforms. runTask?.dependsOn(prepareForRun) } framework('my_framework' [RELEASE]) { // Include a static library instead of a dynamic one into the framework. isStatic = true } }
Learn more about building native binaries.
Cinteropscinterops is a collection of descriptions for interop with native libraries. To provide interop with a library, add an entry to cinterops and define its parameters:
Name
Description
definitionFile
The .def file describing the native API.
packageName
Package prefix for the generated Kotlin API.
compilerOpts
Options to pass to the compiler by the cinterop tool.
includeDirs
Directories to look for headers.
header
Header to be included in the bindings.
headers
The list of headers to be included in the bindings.
kotlin { linuxX64 { // Replace with a target you need. compilations.getByName("main") { val myInterop by cinterops.creating { // Definition file describing the native API. // The default path is src/nativeInterop/cinterop/<interop-name>.def definitionFile.set(project.file("def-file.def")) // Package to place the Kotlin API generated. packageName("org.sample") // Options to be passed to compiler by cinterop tool. compilerOpts("-Ipath/to/headers") // Directories for header search (an analogue of the -I<path> compiler option). includeDirs.allHeaders("path1", "path2") // A shortcut for includeDirs.allHeaders. includeDirs("include/directory", "another/directory") // Header files to be included in the bindings. header("path/to/header.h") headers("path/to/header1.h", "path/to/header2.h") } val anotherInterop by cinterops.creating { /* ... */ } } } }
kotlin { linuxX64 { // Replace with a target you need. compilations.main { cinterops { myInterop { // Definition file describing the native API. // The default path is src/nativeInterop/cinterop/<interop-name>.def definitionFile = project.file("def-file.def") // Package to place the Kotlin API generated. packageName 'org.sample' // Options to be passed to compiler by cinterop tool. compilerOpts '-Ipath/to/headers' // Directories for header search (an analogue of the -I<path> compiler option). includeDirs.allHeaders("path1", "path2") // A shortcut for includeDirs.allHeaders. includeDirs("include/directory", "another/directory") // Header files to be included in the bindings. header("path/to/header.h") headers("path/to/header1.h", "path/to/header2.h") } anotherInterop { /* ... */ } } } } }
For more cinterop properties, see Definition file.
Android targetsThe Kotlin Multiplatform plugin has a specific function that helps you configure build variants for the Android target:
kotlin { androidTarget { publishLibraryVariants("release") } }
Learn more about compilation for Android.
The androidTarget configuration inside the kotlin {} block doesn't replace the build configuration of any Android project. Learn more about writing build scripts for Android projects in Android developer documentation.
The sourceSets {} block describes source sets of the project. A source set contains Kotlin source files that participate in compilations together, along with their resources and dependencies.
A multiplatform project contains predefined source sets for its targets; developers can also create custom source sets for their needs.
Predefined source setsPredefined source sets are set up automatically upon creation of a multiplatform project. Available predefined source sets are the following:
Name
Description
commonMain
Code and resources shared between all platforms. Available in all multiplatform projects. Used in all main compilations of a project.
commonTest
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: jsTest, jvmMain.
kotlin { //... sourceSets { commonMain { /* ... */ } } }
kotlin { //... sourceSets { commonMain { /* ... */ } } }
Learn more about source sets.
Custom source setsCustom 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 by creating.
kotlin { //... sourceSets { val myMain by creating { /* ... */ } // create a new source set by the name 'MyMain' } }
kotlin { //... sourceSets { myMain { /* ... */ } // create or configure a source set by the name 'myMain' } }
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 parametersConfigurations of source sets are stored inside the corresponding blocks of sourceSets {}. A source set has the following parameters:
Name
Description
kotlin.srcDir
Location of Kotlin source files inside the source set directory.
resources.srcDir
Location of resources inside the source set directory.
dependsOn
Connection with another source set.
dependencies
Dependencies of the source set.
languageSettings
Language settings applied to the shared source set.
kotlin { //... sourceSets { commonMain { kotlin.srcDir("src") resources.srcDir("res") dependencies { /* ... */ } } } }
kotlin { //... sourceSets { commonMain { kotlin.srcDir('src') resources.srcDir('res') dependencies { /* ... */ } } } }
CompilationsA 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 compilationsPredefined compilations are created automatically for each target of a project except for Android targets. Available predefined compilations are the following:
Name
Description
main
Compilation for production sources.
test
Compilation for tests.
kotlin { jvm { val main by compilations.getting { output // get the main compilation output } compilations["test"].runtimeDependencyFiles // get the test runtime classpath } }
kotlin { jvm { compilations.main.output // get the main compilation output compilations.test.runtimeDependencyFiles // get the test runtime classpath } }
Custom compilationsIn addition to predefined compilations, you can create your own custom compilations. To do that, set up an associateWith relation between the new and the main compilation. If you're using the Kotlin Gradle DSL, mark custom compilations with by creating:
kotlin { jvm { compilations { val main by getting val integrationTest by creating { // Import main and its classpath as dependencies and establish internal visibility associateWith(main) defaultSourceSet { dependencies { implementation(kotlin("test-junit")) /* ... */ } } // Create a test task to run the tests produced by this compilation testRuns.create("integration") { // Configure the test task setExecutionSourceFrom(integrationTest) } } } } }
kotlin { jvm { compilations.create('integrationTest') { def main = compilations.main // Import main and its classpath as dependencies and establish internal visibility associateWith(main) defaultSourceSet { dependencies { implementation kotlin('test-junit') /* ... */ } } // Create a test task to run the tests produced by this compilation testRuns.create('integration') { // Configure the test task setExecutionSourceFrom(compilations.integrationTest) } } } }
By associating compilations, you add the main compilation output as a dependency and establish the internal visibility between compilations.
Learn more about creating custom compilations.
Compilation parametersA compilation has the following parameters:
Name
Description
defaultSourceSet
The compilation's default source set.
kotlinSourceSets
Source sets participating in the compilation.
allKotlinSourceSets
Source sets participating in the compilation and their connections via dependsOn().
compilerOptions
Compiler options applied to the compilation. For the list of available options, see Compiler options.
compileKotlinTask
Gradle task for compiling Kotlin sources.
compileKotlinTaskName
Name of compileKotlinTask.
compileAllTaskName
Name of the Gradle task for compiling all sources of a compilation.
output
The compilation output.
compileDependencyFiles
Compile-time dependency files (classpath) of the compilation. For all Kotlin/Native compilations, this automatically includes standard library and platform dependencies.
runtimeDependencyFiles
Runtime dependency files (classpath) of the compilation.
kotlin { jvm { val main by compilations.getting { compileTaskProvider.configure { compilerOptions { // Set up the Kotlin compiler options for the 'main' compilation: jvmTarget.set(JvmTarget.JVM_1_8) } } compileKotlinTask // get the Kotlin task 'compileKotlinJvm' output // get the main compilation output } compilations["test"].runtimeDependencyFiles // get the test runtime classpath } // Configure all compilations of all targets: compilerOptions { allWarningsAsErrors.set(true) } }
kotlin { jvm { compilations.main { compileTaskProvider.configure { compilerOptions { // Setup the Kotlin compiler options for the 'main' compilation: jvmTarget = JvmTarget.JVM_1_8 } } } compilations.main.compileKotlinTask // get the Kotlin task 'compileKotlinJvm' compilations.main.output // get the main compilation output compilations.test.runtimeDependencyFiles // get the test runtime classpath } // Configure all compilations of all targets: compilerOptions { allWarningsAsErrors = true } }
Compiler optionsYou can configure compiler options in your projects at three different levels:
Extension level, in the kotlin {} block.
Target level, in a target block.
Compilation unit level, usually in a specific compilation task.
Settings at a higher level work as defaults for the level below:
Compiler options set at the extension level are the default for target-level options, including shared source sets like commonMain, nativeMain, and commonTest.
Compiler options set at the target level are the default for options at the compilation unit (task) level, like compileKotlinJvm and compileTestKotlinJvm tasks.
Configurations made at a lower level override similar settings at higher levels:
Task-level compiler options override similar settings at the target or extension level.
Target-level compiler options override similar settings at the extension level.
For the list of possible compiler options, see All compiler options.
Extension levelTo configure compiler options for all targets in your project, use the compilerOptions {} block at the top level:
kotlin { // Configures all compilations of all targets compilerOptions { allWarningsAsErrors.set(true) } }
kotlin { // Configures all compilations of all targets: compilerOptions { allWarningsAsErrors = true } }
Target levelTo configure compiler options for a specific target in your project, use the compilerOptions {} block inside the target block:
kotlin { jvm { // Configures all compilations of the JVM target compilerOptions { allWarningsAsErrors.set(true) } } }
kotlin { jvm { // Configures all compilations of the JVM target compilerOptions { allWarningsAsErrors = true } } }
Compilation unit levelTo configure compiler options for a specific task, use the compilerOptions {} block inside the task:
task.named<KotlinJvmCompile>("compileKotlinJvm") { compilerOptions { allWarningsAsErrors.set(true) } }
task.named<KotlinJvmCompile>("compileKotlinJvm") { compilerOptions { allWarningsAsErrors = true } }
To configure compiler options for a specific compilation, use the compilerOptions {} block within the compilation's task provider:
kotlin { jvm { compilations.named(KotlinCompilation.MAIN_COMPILATION_NAME) { compileTaskProvider.configure { // Configures the 'main' compilation: compilerOptions { allWarningsAsErrors.set(true) } } } } }
kotlin { jvm { compilations.named(KotlinCompilation.MAIN_COMPILATION_NAME) { compileTaskProvider.configure { // Configures the 'main' compilation: compilerOptions { allWarningsAsErrors = true } } } } }
Migrate fromkotlinOptions {} to compilerOptions {}
Before Kotlin 2.2.0, you could configure compiler options using the kotlinOptions {} block. Since the kotlinOptions {} block is deprecated in Kotlin 2.2.0, you need to use the compilerOptions {} block in your build scripts instead. See Migrate from kotlinOptions{} to compilerOptions{}, for more information.
The 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:
Name
Description
api
Dependencies used in the API of the current module.
implementation
Dependencies used in the module but not exposed outside it.
compileOnly
Dependencies used only for compilation of the current module.
runtimeOnly
Dependencies available at runtime but not visible during compilation of any module.
kotlin { //... sourceSets { commonMain { dependencies { api("com.example:foo-metadata:1.0") } } jvmMain { dependencies { implementation("com.example:foo-jvm:1.0") } } } }
kotlin { //... sourceSets { commonMain { dependencies { api 'com.example:foo-metadata:1.0' } } jvmMain { dependencies { implementation 'com.example:foo-jvm:1.0' } } } }
Additionally, source sets can depend on each other and form a hierarchy. In this case, the dependsOn() relation is used.
The languageSettings {} block in a source set defines certain aspects of project analysis and compilation. Use the languageSettings {} block only to configure settings that apply specifically to a shared source set. For all other cases, use the compilerOptions {} block to configure compiler options at the extension or target level.
The following language settings are available:
Name
Description
languageVersion
Provides source compatibility with the specified version of Kotlin.
apiVersion
Allows using declarations only from the specified version of Kotlin bundled libraries.
enableLanguageFeature
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.
optIn
Allows using the specified opt-in annotation.
progressiveMode
Enables the progressive mode.
kotlin { sourceSets.all { languageSettings.apply { languageVersion = "2.2" // possible values: "1.8", "1.9", "2.0", "2.1" apiVersion = "2.2" // possible values: "1.8", "1.9", "2.0", "2.1" enableLanguageFeature("InlineClasses") // language feature name optIn("kotlin.ExperimentalUnsignedTypes") // annotation FQ-name progressiveMode = true // false by default } } }
kotlin { sourceSets.all { languageSettings { languageVersion = '2.2' // possible values: '1.8', '1.9', '2.0', '2.1' apiVersion = '2.2' // possible values: '1.8', '1.9', '2.0', '2.1' enableLanguageFeature('InlineClasses') // language feature name optIn('kotlin.ExperimentalUnsignedTypes') // annotation FQ-name progressiveMode = true // false by default } } }
Last modified: 13 August 2025
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4