diff --git a/docs/topics/configure-build-for-eap.md b/docs/topics/configure-build-for-eap.md index be0fad1c414..7a25a6b63a3 100644 --- a/docs/topics/configure-build-for-eap.md +++ b/docs/topics/configure-build-for-eap.md @@ -31,12 +31,13 @@ Alternatively, you can specify the EAP version in the `pluginManagement` block i Here is an example for the Multiplatform project. - + + -```groovy +```kotlin plugins { - id 'java' - id 'org.jetbrains.kotlin.multiplatform' version 'KOTLIN-EAP-VERSION' + java + kotlin("multiplatform") version "KOTLIN-EAP-VERSION" } repositories { @@ -44,10 +45,13 @@ repositories { } ``` -```kotlin + + + +```groovy plugins { - java - kotlin("multiplatform") version "KOTLIN-EAP-VERSION" + id 'java' + id 'org.jetbrains.kotlin.multiplatform' version 'KOTLIN-EAP-VERSION' } repositories { @@ -55,6 +59,7 @@ repositories { } ``` + ### Adjust versions in dependencies @@ -74,20 +79,25 @@ Here is an example. For the **kotlinx.coroutines** library, add the version number – `%coroutinesEapVersion%` – that is compatible with `%kotlinEapVersion%`. - + + -```groovy +```kotlin dependencies { - implementation "org.jetbrains.kotlinx:kotlinx-coroutines-core:%coroutinesEapVersion%" + implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:%coroutinesEapVersion%") } ``` -```kotlin + + + +```groovy dependencies { - implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:%coroutinesEapVersion%") + implementation "org.jetbrains.kotlinx:kotlinx-coroutines-core:%coroutinesEapVersion%" } ``` + ## Configure in Maven diff --git a/docs/topics/curl.md b/docs/topics/curl.md index 03b02fe156a..1878c9a135a 100644 --- a/docs/topics/curl.md +++ b/docs/topics/curl.md @@ -68,11 +68,12 @@ the missing directories will have to be created before any new files can be adde Use the following `build.gradle(.kts)` Gradle build file: - + + -```groovy +```kotlin plugins { - id 'org.jetbrains.kotlin.multiplatform' version '%kotlinVersion%' + kotlin("multiplatform") version "%kotlinVersion%" } repositories { @@ -80,12 +81,12 @@ repositories { } kotlin { - linuxX64("native") { // on Linux - // macosX64("native") { // on macOS - // mingwX64("native") { //on Windows - compilations.main.cinterops { - interop - } + linuxX64("native") { // on Linux + // macosX64("native") { // on x86_64 macOS + // macosArm64("native") { // on Apple Silicon macOS + // mingwX64("native") { // on Windows + val main by compilations.getting + val interop by main.cinterops.creating binaries { executable() @@ -93,15 +94,18 @@ kotlin { } } -wrapper { +tasks.wrapper { gradleVersion = "%gradleVersion%" - distributionType = "ALL" + distributionType = Wrapper.DistributionType.ALL } ``` -```kotlin + + + +```groovy plugins { - kotlin("multiplatform") version "%kotlinVersion%" + id 'org.jetbrains.kotlin.multiplatform' version '%kotlinVersion%' } repositories { @@ -110,10 +114,12 @@ repositories { kotlin { linuxX64("native") { // on Linux - // macosX64("native") { // on macOS + // macosX64("native") { // on x86_64 macOS + // macosArm64("native") { // on Apple Silicon macOS // mingwX64("native") { // on Windows - val main by compilations.getting - val interop by main.cinterops.creating + compilations.main.cinterops { + interop + } binaries { executable() @@ -121,12 +127,13 @@ kotlin { } } -tasks.wrapper { +wrapper { gradleVersion = "%gradleVersion%" - distributionType = Wrapper.DistributionType.ALL + distributionType = "ALL" } ``` + The project file configures the C interop as an additional step of the build. diff --git a/docs/topics/generics.md b/docs/topics/generics.md index c95fefd793a..765a14344f4 100644 --- a/docs/topics/generics.md +++ b/docs/topics/generics.md @@ -271,7 +271,7 @@ fun singletonList(item: T): List { // ... } -fun T.basicToString(): String { // extension function +fun T.basicToString(): String { // extension function // ... } ``` diff --git a/docs/topics/gradle.md b/docs/topics/gradle.md index 7f75db04e27..e984e9bfde4 100644 --- a/docs/topics/gradle.md +++ b/docs/topics/gradle.md @@ -9,20 +9,25 @@ Apply the Kotlin Gradle plugin by using the [Gradle plugins DSL](https://docs.gr The Kotlin Gradle plugin and the `kotlin-multiplatform` plugin %kotlinVersion% require Gradle %minGradleVersion% or later. - + + -```groovy +```kotlin plugins { - id 'org.jetbrains.kotlin.<...>' version '%kotlinVersion%' + kotlin("<...>") version "%kotlinVersion%" } ``` -```kotlin + + + +```groovy plugins { - kotlin("<...>") version "%kotlinVersion%" + id 'org.jetbrains.kotlin.<...>' version '%kotlinVersion%' } ``` + The placeholder `<...>` should be replaced with the name of one of the plugins that will be discussed in subsequent sections. @@ -36,40 +41,50 @@ require the `kotlin-multiplatform` plugin. [Learn more about the plugin](mpp-dis > {type="note"} - + + -```groovy +```kotlin plugins { - id 'org.jetbrains.kotlin.multiplatform' version '%kotlinVersion%' + kotlin("multiplatform") version "%kotlinVersion%" } ``` -```kotlin + + + +```groovy plugins { - kotlin("multiplatform") version "%kotlinVersion%" + id 'org.jetbrains.kotlin.multiplatform' version '%kotlinVersion%' } ``` + ## Targeting the JVM To target the JVM, apply the Kotlin JVM plugin. - + + -```groovy +```kotlin plugins { - id "org.jetbrains.kotlin.jvm" version "%kotlinVersion%" + kotlin("jvm") version "%kotlinVersion%" } ``` -```kotlin + + + +```groovy plugins { - kotlin("jvm") version "%kotlinVersion%" + id "org.jetbrains.kotlin.jvm" version "%kotlinVersion%" } ``` + The `version` should be literal in this block, and it cannot be applied from another build script. @@ -96,7 +111,17 @@ project The corresponding `sourceSets` property should be updated if you are not using the default convention: - + + + +```kotlin +sourceSets.main { + java.srcDirs("src/main/myJava", "src/main/myKotlin") +} +``` + + + ```groovy sourceSets { @@ -105,32 +130,32 @@ sourceSets { } ``` -```kotlin -sourceSets.main { - java.srcDirs("src/main/myJava", "src/main/myKotlin") -} -``` - + ## Targeting JavaScript When targeting only JavaScript, use the `kotlin-js` plugin. [Learn more](js-project-setup.md) - + + -```groovy +```kotlin plugins { - id 'org.jetbrains.kotlin.js' version '%kotlinVersion%' + kotlin("js") version "%kotlinVersion%" } ``` -```kotlin + + + +```groovy plugins { - kotlin("js") version "%kotlinVersion%" + id 'org.jetbrains.kotlin.js' version '%kotlinVersion%' } ``` + ### Kotlin and Java sources for JavaScript @@ -138,24 +163,29 @@ plugins { This plugin only works for Kotlin files, so it is recommended that you keep Kotlin and Java files separate (if the project contains Java files). If you don't store them separately, specify the source folder in the `sourceSets` block: - + + -```groovy +```kotlin kotlin { - sourceSets { - main.kotlin.srcDirs += 'src/main/myKotlin' + sourceSets["main"].apply { + kotlin.srcDir("src/main/myKotlin") } } ``` -```kotlin + + + +```groovy kotlin { - sourceSets["main"].apply { - kotlin.srcDir("src/main/myKotlin") + sourceSets { + main.kotlin.srcDirs += 'src/main/myKotlin' } } ``` + ## Targeting Android @@ -167,32 +197,37 @@ It's recommended to use Android Studio for creating Android applications. [Learn To add a dependency on a library, set the dependency of the required [type](#dependency-types) (for example, `implementation`) in the `dependencies` block of the source sets DSL. - + + -```groovy +```kotlin kotlin { sourceSets { - commonMain { + val commonMain by getting { dependencies { - implementation 'com.example:my-library:1.0' + implementation("com.example:my-library:1.0") } } } } ``` -```kotlin + + + +```groovy kotlin { sourceSets { - val commonMain by getting { + commonMain { dependencies { - implementation("com.example:my-library:1.0") + implementation 'com.example:my-library:1.0' } } } } ``` + Alternatively, you can [set dependencies at the top level](#set-dependencies-at-the-top-level). @@ -265,32 +300,37 @@ test dependencies for each test source set: Kotlin/Native targets do not require additional test dependencies, and the `kotlin.test` API implementations are built-in. - + + -```groovy +```kotlin kotlin { sourceSets { - commonTest { + val commonTest by getting { dependencies { - implementation kotlin("test") // This brings all the platform dependencies automatically + implementation(kotlin("test")) // This brings all the platform dependencies automatically } } } } ``` -```kotlin + + + +```groovy kotlin { sourceSets { - val commonTest by getting { + commonTest { dependencies { - implementation(kotlin("test")) // This brings all the platform dependencies automatically + implementation kotlin("test") // This brings all the platform dependencies automatically } } } } ``` + > You can use shorthand for a dependency on a Kotlin module, for example, kotlin("test") for "org.jetbrains.kotlin:kotlin-test". @@ -308,9 +348,10 @@ or [`useTestNG()`](https://docs.gradle.org/current/javadoc/org/gradle/api/tasks/ test task of your build script. The following example is for an MPP project: - + + -```groovy +```kotlin kotlin { jvm { testRuns["test"].executionTask.configure { @@ -318,16 +359,19 @@ kotlin { } } sourceSets { - commonTest { + val commonTest by getting { dependencies { - implementation kotlin("test") + implementation(kotlin("test")) } } } } ``` -```kotlin + + + +```groovy kotlin { jvm { testRuns["test"].executionTask.configure { @@ -335,30 +379,22 @@ kotlin { } } sourceSets { - val commonTest by getting { + commonTest { dependencies { - implementation(kotlin("test")) + implementation kotlin("test") } } } } ``` + The following example is for a JVM project: - - -```groovy -dependencies { - testImplementation 'org.jetbrains.kotlin:kotlin-test' -} - -test { - useTestNG() -} -``` + + ```kotlin dependencies { @@ -372,6 +408,20 @@ tasks { } ``` + + + +```groovy +dependencies { + testImplementation 'org.jetbrains.kotlin:kotlin-test' +} + +test { + useTestNG() +} +``` + + [Learn how to test code using JUnit on the JVM](jvm-test-using-junit.md). @@ -390,63 +440,73 @@ If you use a kotlinx library and need a platform-specific dependency, you can us of libraries with suffixes such as `-jvm` or `-js`, for example, `kotlinx-coroutines-core-jvm`. You can also use the library's base artifact name instead – `kotlinx-coroutines-core`. - + + -```groovy +```kotlin kotlin { sourceSets { - jvmMain { + val jvmMain by getting { dependencies { - implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core-jvm:%coroutinesVersion%' + implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core-jvm:%coroutinesVersion%") } } } } ``` -```kotlin + + + +```groovy kotlin { sourceSets { - val jvmMain by getting { + jvmMain { dependencies { - implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core-jvm:%coroutinesVersion%") + implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core-jvm:%coroutinesVersion%' } } } } ``` + If you use a multiplatform library and need to depend on the shared code, set the dependency only once, in the shared source set. Use the library's base artifact name, such as `kotlinx-coroutines-core` or `ktor-client-core`. - + + -```groovy +```kotlin kotlin { sourceSets { - commonMain { + val commonMain by getting { dependencies { - implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:%coroutinesVersion%' + implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:%coroutinesVersion%") } } } } ``` -```kotlin + + + +```groovy kotlin { sourceSets { - val commonMain by getting { + commonMain { dependencies { - implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:%coroutinesVersion%") + implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:%coroutinesVersion%' } } } } ``` + ### Set dependencies at the top level @@ -455,20 +515,25 @@ Alternatively, you can specify the dependencies at the top level, using the foll ``. This can be helpful for some Gradle built-in dependencies, like `gradleApi()`, `localGroovy()`, or `gradleTestKit()`, which are not available in the source sets' dependency DSL. - + + -```groovy +```kotlin dependencies { - commonMainImplementation 'com.example:my-library:1.0' + "commonMainImplementation"("com.example:my-library:1.0") } ``` -```kotlin + + + +```groovy dependencies { - "commonMainImplementation"("com.example:my-library:1.0") + commonMainImplementation 'com.example:my-library:1.0' } ``` + ## Annotation processing @@ -531,7 +596,20 @@ When targeting JavaScript, the tasks are called `compileKotlinJs` for production To configure a single task, use its name. Examples: - + + + +```kotlin +import org.jetbrains.kotlin.gradle.tasks.KotlinCompile +// ... + +val compileKotlin: KotlinCompile by tasks + +compileKotlin.kotlinOptions.suppressWarnings = true +``` + + + ```groovy compileKotlin { @@ -547,15 +625,7 @@ compileKotlin { } ``` -```kotlin -import org.jetbrains.kotlin.gradle.tasks.KotlinCompile -// ... - -val compileKotlin: KotlinCompile by tasks - -compileKotlin.kotlinOptions.suppressWarnings = true -``` - + Note that with the Gradle Kotlin DSL, you should get the task from the project's `tasks` first. @@ -564,20 +634,24 @@ Use the `Kotlin2JsCompile` and `KotlinCompileCommon` types for JS and common tar It is also possible to configure all of the Kotlin compilation tasks in the project: - + + -```groovy -tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).configureEach { +```kotlin +tasks.withType().configureEach { kotlinOptions { /*...*/ } } ``` -```kotlin -tasks.withType().configureEach { + + + +```groovy +tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).configureEach { kotlinOptions { /*...*/ } } ``` - + Here is a complete list of options for Gradle tasks: @@ -688,15 +762,8 @@ A Java toolchain: Use the following code to set a toolchain. Replace the placeholder `` with the JDK version you would like to use: - - -```groovy -kotlin { - jvmToolchain { - languageVersion.set(JavaLanguageVersion.of()) // "8" - } -} -``` + + ```kotlin kotlin { @@ -706,22 +773,25 @@ kotlin { } ``` - - -Note that setting a toolchain via the `kotlin` extension will update the toolchain for Java compile tasks as well. - -You can set a toolchain via the `java` extension, and Kotlin compilation tasks will use it: - + + ```groovy -java { - toolchain { - languageVersion.set(JavaLanguageVersion.of()) // "8" +kotlin { + jvmToolchain { + languageVersion.set(JavaLanguageVersion.of()) // "8" } } ``` + + + +Note that setting a toolchain via the `kotlin` extension will update the toolchain for Java compile tasks as well. + +You can set a toolchain via the `java` extension, and Kotlin compilation tasks will use it: + ```kotlin java { toolchain { @@ -730,8 +800,6 @@ java { } ``` - - To set any JDK (even local) for the specific task, use the Task DSL. #### Setting JDK version with the Task DSL @@ -740,49 +808,41 @@ The Task DSL allows setting any JDK version for any task implementing the `UsesK At the moment, these tasks are `KotlinCompile` and `KaptTask`. If you want Gradle to search for the major JDK version, replace the placeholder in your build script: - + + -```groovy -JavaToolchainService service = project.getExtensions().getByType(JavaToolchainService.class) -Provider customLauncher = service.launcherFor { +```kotlin +val service = project.extensions.getByType() +val customLauncher = service.launcherFor { it.languageVersion.set(JavaLanguageVersion.of()) // "8" } project.tasks - .matching { it instanceof UsesKotlinJavaToolchain && it.name == 'compileKotlin' } + .matching { it is UsesKotlinJavaToolchain && it.name == "compileKotlin" } .configureEach { it.kotlinJavaToolchain.toolchain.use(customLauncher) } ``` -```kotlin -val service = project.extensions.getByType() -val customLauncher = service.launcherFor { + + + +```groovy +JavaToolchainService service = project.getExtensions().getByType(JavaToolchainService.class) +Provider customLauncher = service.launcherFor { it.languageVersion.set(JavaLanguageVersion.of()) // "8" } project.tasks - .matching { it is UsesKotlinJavaToolchain && it.name == "compileKotlin" } + .matching { it instanceof UsesKotlinJavaToolchain && it.name == 'compileKotlin' } .configureEach { it.kotlinJavaToolchain.toolchain.use(customLauncher) } ``` + Or you can specify the path to your local JDK and replace the placeholder `` with this JDK version: - - -```groovy -project.tasks - .matching { it is UsesKotlinJavaToolchain && it.name == "compileKotlin" } - .configureEach { - it.kotlinJavaToolchain.jdk.use( - '/path/to/your/jdk', // Put a path to your JDK - JavaVersion. // For example, JavaVersion.17 - ) - } -``` - ```kotlin project.tasks .matching { it is UsesKotlinJavaToolchain && it.name == "compileKotlin" } @@ -794,8 +854,6 @@ project.tasks } ``` - - ## Generating documentation To generate documentation for Kotlin projects, use [Dokka](https://github.com/Kotlin/dokka); @@ -850,34 +908,32 @@ Each of the options in the following list overrides the ones that came before it * You can specify arguments in the `kotlin` extension: - - - ```groovy + + + + ```kotlin kotlin { - kotlinDaemonJvmArgs = ["-Xmx486m", "-Xms256m", "-XX:+UseParallelGC"] + kotlinDaemonJvmArgs = listOf("-Xmx486m", "-Xms256m", "-XX:+UseParallelGC") } ``` - ```kotlin + + + + ```groovy kotlin { - kotlinDaemonJvmArgs = listOf("-Xmx486m", "-Xms256m", "-XX:+UseParallelGC") + kotlinDaemonJvmArgs = ["-Xmx486m", "-Xms256m", "-XX:+UseParallelGC"] } ``` - + + * You can specify arguments for a specific task: - - - - ```groovy - tasks - .matching { it.name == "compileKotlin" && it instanceof CompileUsingKotlinDaemon } - .configureEach { - kotlinDaemonJvmArguments.set(["-Xmx1g", "-Xms512m"]) - } - ``` + + + ```kotlin tasks .matching { it.name == "compileKotlin" && it is CompileUsingKotlinDaemon } @@ -885,7 +941,19 @@ Each of the options in the following list overrides the ones that came before it (this as CompileUsingKotlinDaemon).kotlinDaemonJvmArguments.set(listOf("-Xmx486m", "-Xms256m", "-XX:+UseParallelGC")) } ``` + + + + ```groovy + tasks + .matching { it.name == "compileKotlin" && it instanceof CompileUsingKotlinDaemon } + .configureEach { + kotlinDaemonJvmArguments.set(["-Xmx1g", "-Xms512m"]) + } + ``` + + > In this case a new Kotlin daemon instance can start on task execution. Learn more about [Kotlin daemon's behavior with JVM arguments](#kotlin-daemon-s-behavior-with-jvm-arguments). diff --git a/docs/topics/js/js-external-declarations-with-dukat.md b/docs/topics/js/js-external-declarations-with-dukat.md index 65f246909ff..750ea458884 100644 --- a/docs/topics/js/js-external-declarations-with-dukat.md +++ b/docs/topics/js/js-external-declarations-with-dukat.md @@ -19,20 +19,25 @@ if and when Dukat should generate declarations: at build time, and manually via The `npm` dependency function takes a third parameter after the package name and version: `generateExternals`. This allows you to control whether Dukat should generate declarations for a specific dependency: - + + -```groovy +```kotlin dependencies { - implementation(npm('decamelize', '4.0.0', true)) + implementation(npm("decamelize", "4.0.0", generateExternals = true)) } ``` -```kotlin + + + +```groovy dependencies { - implementation(npm("decamelize", "4.0.0", generateExternals = true)) + implementation(npm('decamelize', '4.0.0', true)) } ``` + If the repository of the dependency you wish to use does not provide TypeScript definitions, you can also use types diff --git a/docs/topics/js/js-ir-compiler.md b/docs/topics/js/js-ir-compiler.md index 903e11ec53f..9b4a3d5f64f 100644 --- a/docs/topics/js/js-ir-compiler.md +++ b/docs/topics/js/js-ir-compiler.md @@ -85,24 +85,29 @@ only the ones needed at startup; other properties receive their values later whe As an experimental feature, lazy initialization of top-level properties requires an opt-in. To use the lazy initialization of top-level properties, add the `-Xir-property-lazy-initialization` option when compiling the code with the JS IR compiler: - - -```groovy -tasks.withType(Kotlin2JsCompile) { + + + +```kotlin +tasks.withType { kotlinOptions { freeCompilerArgs += "-Xir-property-lazy-initialization" } } ``` -```kotlin -tasks.withType { + + + +```groovy +tasks.withType(Kotlin2JsCompile) { kotlinOptions { freeCompilerArgs += "-Xir-property-lazy-initialization" } } ``` + ## Preview: generation of TypeScript declaration files (d.ts) diff --git a/docs/topics/js/js-modules.md b/docs/topics/js/js-modules.md index 8c22823a6fd..77326f73f00 100644 --- a/docs/topics/js/js-modules.md +++ b/docs/topics/js/js-modules.md @@ -44,12 +44,8 @@ system, the instructions are slightly different. To select module kind, set the `moduleKind` compiler option in the Gradle build script. - - -```groovy -compileKotlinJs.kotlinOptions.moduleKind = "commonjs" - -``` + + ```kotlin tasks.named("compileKotlinJs").configure { @@ -57,6 +53,14 @@ tasks.named("compileKotlinJs").configure { } ``` + + + +```groovy +compileKotlinJs.kotlinOptions.moduleKind = "commonjs" +``` + + Available values are: `umd` (default), `commonjs`, `amd`, `plain`. diff --git a/docs/topics/js/js-project-setup.md b/docs/topics/js/js-project-setup.md index c8faebf98aa..ec5c4bc6ea3 100644 --- a/docs/topics/js/js-project-setup.md +++ b/docs/topics/js/js-project-setup.md @@ -15,20 +15,25 @@ Kotlin/JS target that suits you best. Don't forget to choose the language for th Alternatively, you can apply the `org.jetbrains.kotlin.js` plugin to a Gradle project manually in the Gradle build file (`build.gradle` or `build.gradle.kts`). - + + -```groovy +```kotlin plugins { - id 'org.jetbrains.kotlin.js' version '%kotlinVersion%' + kotlin("js") version "'%kotlinVersion%" } ``` -```kotlin + + + +```groovy plugins { - kotlin("js") version "'%kotlinVersion%" + id 'org.jetbrains.kotlin.js' version '%kotlinVersion%' } ``` + The Kotlin/JS Gradle plugin lets you manage aspects of your project in the `kotlin` section of the build script. @@ -86,26 +91,43 @@ This allows developers to build, run and test simple projects without additional Like any other Gradle projects, Kotlin/JS projects support traditional Gradle [dependency declarations](https://docs.gradle.org/current/userguide/declaring_dependencies.html) in the `dependencies` section of the build script. - + + -```groovy +```kotlin dependencies { - implementation 'org.example.myproject:1.1.0' + implementation("org.example.myproject", "1.1.0") } ``` -```kotlin + + + +```groovy dependencies { - implementation("org.example.myproject", "1.1.0") + implementation 'org.example.myproject:1.1.0' } ``` + The Kotlin/JS Gradle plugin also supports dependency declarations for particular source sets in the `kotlin` section of the build script. - + + + +```kotlin +kotlin { + sourceSets["main"].dependencies { + implementation("org.example.myproject", "1.1.0") + } +} +``` + + + ```groovy kotlin { @@ -119,14 +141,7 @@ kotlin { } ``` -```kotlin -kotlin { - sourceSets["main"].dependencies { - implementation("org.example.myproject", "1.1.0") - } -} -``` - + Please note that not all libraries available for the Kotlin programming language are available when targeting JavaScript: @@ -143,20 +158,25 @@ for all Kotlin/JS projects, and as such is implicit – no artifacts need to be If your project contains tests written in Kotlin, you should add a dependency on the [kotlin.test](https://kotlinlang.org/api/latest/kotlin.test/index.html) library: - + + -```groovy +```kotlin dependencies { - testImplementation 'org.jetbrains.kotlin:kotlin-test-js' + testImplementation(kotlin("test-js")) } ``` -```kotlin + + + +```groovy dependencies { - testImplementation(kotlin("test-js")) + testImplementation 'org.jetbrains.kotlin:kotlin-test-js' } ``` + ### npm dependencies @@ -170,20 +190,25 @@ declare any other dependencies. To declare an npm dependency, pass its name and version to the `npm()` function inside a dependency declaration. You can also specify one or multiple version range based on [npm's semver syntax](https://docs.npmjs.com/misc/semver#versions). - + + -```groovy +```kotlin dependencies { - implementation npm('react', '> 14.0.0 <=16.9.0') + implementation(npm("react", "> 14.0.0 <=16.9.0")) } ``` -```kotlin + + + +```groovy dependencies { - implementation(npm("react", "> 14.0.0 <=16.9.0")) + implementation npm('react', '> 14.0.0 <=16.9.0') } ``` + To download and install your declared dependencies during build time, the plugin manages its own installation of the @@ -457,14 +482,15 @@ To set another location for project distribution files, add the `distribution` b assign a value to the `directory` property. Once you run a project build task, Gradle will save the output bundle in this location together with project resources. - + + -```groovy +```kotlin kotlin { js { browser { distribution { - directory = file("$projectDir/output/") + directory = File("$projectDir/output/") } } binaries.executable() @@ -473,12 +499,15 @@ kotlin { } ``` -```kotlin + + + +```groovy kotlin { js { browser { distribution { - directory = File("$projectDir/output/") + directory = file("$projectDir/output/") } } binaries.executable() @@ -487,6 +516,7 @@ kotlin { } ``` + ## Module name diff --git a/docs/topics/jvm/java-interop.md b/docs/topics/jvm/java-interop.md index 585a9f64308..9f0e592fccf 100644 --- a/docs/topics/jvm/java-interop.md +++ b/docs/topics/jvm/java-interop.md @@ -34,7 +34,7 @@ import java.util.Calendar fun calendarDemo() { val calendar = Calendar.getInstance() - if (calendar.firstDayOfWeek == Calendar.SUNDAY) { // call getFirstDayOfWeek() + if (calendar.firstDayOfWeek == Calendar.SUNDAY) { // call getFirstDayOfWeek() calendar.firstDayOfWeek = Calendar.MONDAY // call setFirstDayOfWeek() } if (!calendar.isLenient) { // call isLenient() diff --git a/docs/topics/jvm/jvm-test-using-junit.md b/docs/topics/jvm/jvm-test-using-junit.md index 8b663c19ff4..c0c6c39b4e0 100644 --- a/docs/topics/jvm/jvm-test-using-junit.md +++ b/docs/topics/jvm/jvm-test-using-junit.md @@ -16,40 +16,50 @@ To get started, first download and install the latest version of [IntelliJ IDEA] 2. Open the `build.gradle(.kts)` file and add the following dependency to the Gradle configuration. This dependency will allow you to work with `kotlin.test` and `JUnit`: - + + - ```groovy + ```kotlin dependencies { // Other dependencies. - testImplementation 'org.jetbrains.kotlin:kotlin-test' + testImplementation(kotlin("test")) } ``` - ```kotlin + + + + ```groovy dependencies { // Other dependencies. - testImplementation(kotlin("test")) + testImplementation 'org.jetbrains.kotlin:kotlin-test' } ``` + 3. Add the `test` task to the `build.gradle(.kts)` file: - + + - ```groovy - test { + ```kotlin + tasks.test { useJUnitPlatform() } ``` - ```kotlin - tasks.test { + + + + ```groovy + test { useJUnitPlatform() } ``` + > If you created the project using the **Project Wizard**, the task will be added automatically. diff --git a/docs/topics/kapt.md b/docs/topics/kapt.md index 98925a53e77..7f2c37bf61d 100644 --- a/docs/topics/kapt.md +++ b/docs/topics/kapt.md @@ -11,20 +11,24 @@ Please read below about how to apply the *kapt* plugin to your Gradle/Maven buil Apply the `kotlin-kapt` Gradle plugin: - + + -```groovy +```kotlin plugins { - id "org.jetbrains.kotlin.kapt" version "%kotlinVersion%" -} + kotlin("kapt") version "%kotlinVersion%" } ``` -```kotlin + + + +```groovy plugins { - kotlin("kapt") version "%kotlinVersion%" + id "org.jetbrains.kotlin.kapt" version "%kotlinVersion%" } ``` + Alternatively, you can use the `apply plugin` syntax: @@ -35,20 +39,26 @@ apply plugin: 'kotlin-kapt' Then add the respective dependencies using the `kapt` configuration in your `dependencies` block: - -```groovy + + + +```kotlin dependencies { - kapt 'groupId:artifactId:version' + kapt("groupId:artifactId:version") } ``` -```kotlin + + + +```groovy dependencies { - kapt("groupId:artifactId:version") + kapt 'groupId:artifactId:version' } ``` + If you previously used the [Android support](https://developer.android.com/studio/build/gradle-plugin-3-0-0-migration.html#annotationProcessor_config) diff --git a/docs/topics/lombok.md b/docs/topics/lombok.md index af01362a73d..5b9fed562fe 100644 --- a/docs/topics/lombok.md +++ b/docs/topics/lombok.md @@ -37,22 +37,27 @@ for [`@Builder` in YouTrack](https://youtrack.jetbrains.com/issue/KT-46959). Apply the `kotlin-plugin-lombok` Gradle plugin in the `build.gradle(.kts)` file: - + + -```groovy +```kotlin plugins { - id 'org.jetbrains.kotlin.plugin.lombok' version '%kotlinVersion%' - id 'io.freefair.lombok' version '5.3.0' + kotlin("plugin.lombok") version "%kotlinVersion%" + id("io.freefair.lombok") version "5.3.0" } ``` -```kotlin + + + +```groovy plugins { - kotlin("plugin.lombok") version "%kotlinVersion%" - id("io.freefair.lombok") version "5.3.0" + id 'org.jetbrains.kotlin.plugin.lombok' version '%kotlinVersion%' + id 'io.freefair.lombok' version '5.3.0' } ``` + See this [test project with examples of the Lombok compiler plugin in use](https://github.com/kotlin-hands-on/kotlin-lombok-examples/tree/master/kotlin_lombok_gradle/nokapt). @@ -63,20 +68,26 @@ If you use a [Lombok configuration file](https://projectlombok.org/features/conf provide a path to it to the plugin. The path should be relative to the module's directory. Add the following code to your `build.gradle(.kts)` file: - + + -```groovy +```kotlin kotlinLombok { - lombokConfigurationFile file("lombok.config") + lombokConfigurationFile(file("lombok.config")) } ``` -```kotlin + + + + +```groovy kotlinLombok { - lombokConfigurationFile(file("lombok.config")) + lombokConfigurationFile file("lombok.config") } ``` + See this [test project with examples of the Lombok compiler plugin and `lombok.config` in use](https://github.com/kotlin-hands-on/kotlin-lombok-examples/tree/master/kotlin_lombok_gradle/withconfig). diff --git a/docs/topics/mpp/mpp-add-dependencies.md b/docs/topics/mpp/mpp-add-dependencies.md index 1e4e1a0989a..dbc10572bb7 100644 --- a/docs/topics/mpp/mpp-add-dependencies.md +++ b/docs/topics/mpp/mpp-add-dependencies.md @@ -3,32 +3,37 @@ To add a dependency on a library, set a dependency of the required [type](gradle.md#dependency-types) (for example, `implementation`) in the [`dependencies`](mpp-dsl-reference.md#dependencies) block in your [Gradle](gradle.md) build script. - + + -```groovy +```kotlin kotlin { sourceSets { - commonMain { + val commonMain by getting { dependencies { - implementation 'com.example:my-library:1.0' + implementation("com.example:my-library:1.0") } } } } -``` +``` -```kotlin + + + +```groovy kotlin { sourceSets { - val commonMain by getting { + commonMain { dependencies { - implementation("com.example:my-library:1.0") + implementation 'com.example:my-library:1.0' } } } } -``` +``` + Alternatively, you can [set dependencies at the top level](gradle.md#set-dependencies-at-the-top-level). @@ -57,64 +62,73 @@ If you use a kotlinx library and need a platform-specific dependency, you can us of libraries with suffixes such as `-jvm` or `-js`, for example, `kotlinx-coroutines-core-jvm`. You can also use the library base artifact name instead – `kotlinx-coroutines-core`. - + + -```groovy +```kotlin kotlin { sourceSets { - jvmMain { + val jvmMain by getting { dependencies { - implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core-jvm:%coroutinesVersion%' + implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core-jvm:%coroutinesVersion%") } } } } -``` -```kotlin +``` + + + + +```groovy kotlin { sourceSets { - val jvmMain by getting { + jvmMain { dependencies { - implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core-jvm:%coroutinesVersion%") + implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core-jvm:%coroutinesVersion%' } } } } +``` -``` - + If you use a multiplatform library and need to depend on the shared code, set the dependency only once in the shared source set. Use the library base artifact name, such as `kotlinx-coroutines-core` or `ktor-client-core`. - + + -```groovy +```kotlin kotlin { sourceSets { - commonMain { + val commonMain by getting { dependencies { - implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:%coroutinesVersion%' + implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:%coroutinesVersion%") } } } } -``` +``` -```kotlin + + + +```groovy kotlin { sourceSets { - val commonMain by getting { + commonMain { dependencies { - implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:%coroutinesVersion%") + implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:%coroutinesVersion%' } } } } +``` -``` - + diff --git a/docs/topics/mpp/mpp-build-native-binaries.md b/docs/topics/mpp/mpp-build-native-binaries.md index 5c80ad56c6a..a59a3cdff73 100644 --- a/docs/topics/mpp/mpp-build-native-binaries.md +++ b/docs/topics/mpp/mpp-build-native-binaries.md @@ -54,56 +54,66 @@ binaries { You can specify for which build types to create binaries. In the following example, only the `debug` executable is created. - + + -```groovy +```kotlin binaries { - executable([DEBUG]) { + executable(listOf(DEBUG)) { // Binary configuration. } } ``` -```kotlin + + + +```groovy binaries { - executable(listOf(DEBUG)) { + executable([DEBUG]) { // Binary configuration. } } ``` + You can also declare binaries with custom names. - + + -```groovy +```kotlin binaries { - executable('foo', [DEBUG]) { + executable("foo", listOf(DEBUG)) { // Binary configuration. } // It's possible to drop the list of build types (in which case, all the available build types will be used). - executable('bar') { + executable("bar") { // Binary configuration. } } ``` -```kotlin + + + +```groovy binaries { - executable("foo", listOf(DEBUG)) { + executable('foo', [DEBUG]) { // Binary configuration. } // It's possible to drop the list of build types (in which case, all the available build types will be used). - executable("bar") { + executable('bar') { // Binary configuration. } } ``` + The first argument sets a name prefix, which is the default name for the binary file. For example, for Windows the code @@ -121,65 +131,75 @@ binary kind following the pattern: ` {type="note"} - + + -```groovy +```kotlin // Fails if there is no such binary. -binaries['fooDebugExecutable'] -binaries.fooDebugExecutable -binaries.getByName('fooDebugExecutable') +binaries["fooDebugExecutable"] +binaries.getByName("fooDebugExecutable") // Returns null if there is no such binary. -binaries.findByName('fooDebugExecutable') +binaries.findByName("fooDebugExecutable") ``` -```kotlin + + + +```groovy // Fails if there is no such binary. -binaries["fooDebugExecutable"] -binaries.getByName("fooDebugExecutable") +binaries['fooDebugExecutable'] +binaries.fooDebugExecutable +binaries.getByName('fooDebugExecutable') // Returns null if there is no such binary. -binaries.findByName("fooDebugExecutable") +binaries.findByName('fooDebugExecutable') ``` + Alternatively, you can access a binary by its name prefix and build type using typed getters. - + + -```groovy +```kotlin // Fails if there is no such binary. -binaries.getExecutable('foo', DEBUG) +binaries.getExecutable("foo", DEBUG) binaries.getExecutable(DEBUG) // Skip the first argument if the name prefix isn't set. -binaries.getExecutable('bar', 'DEBUG') // You also can use a string for build type. +binaries.getExecutable("bar", "DEBUG") // You also can use a string for build type. // Similar getters are available for other binary kinds: // getFramework, getStaticLib and getSharedLib. // Returns null if there is no such binary. -binaries.findExecutable('foo', DEBUG) +binaries.findExecutable("foo", DEBUG) // Similar getters are available for other binary kinds: // findFramework, findStaticLib and findSharedLib. ``` -```kotlin + + + +```groovy // Fails if there is no such binary. -binaries.getExecutable("foo", DEBUG) +binaries.getExecutable('foo', DEBUG) binaries.getExecutable(DEBUG) // Skip the first argument if the name prefix isn't set. -binaries.getExecutable("bar", "DEBUG") // You also can use a string for build type. +binaries.getExecutable('bar', 'DEBUG') // You also can use a string for build type. // Similar getters are available for other binary kinds: // getFramework, getStaticLib and getSharedLib. // Returns null if there is no such binary. -binaries.findExecutable("foo", DEBUG) +binaries.findExecutable('foo', DEBUG) // Similar getters are available for other binary kinds: // findFramework, findStaticLib and findSharedLib. ``` + ## Export dependencies to binaries @@ -188,56 +208,61 @@ When building an Objective-C framework or a native library (shared or static), y of the current project, but also the classes of its dependencies. Specify which dependencies to export to a binary using the `export` method. - + + -```groovy +```kotlin kotlin { sourceSets { macosMain.dependencies { // Will be exported. - api project(':dependency') - api 'org.example:exported-library:1.0' + api(project(":dependency")) + api("org.example:exported-library:1.0") // Will not be exported. - api 'org.example:not-exported-library:1.0' + api("org.example:not-exported-library:1.0") } } macosX64("macos").binaries { framework { - export project(':dependency') - export 'org.example:exported-library:1.0' + export(project(":dependency")) + export("org.example:exported-library:1.0") } sharedLib { // It's possible to export different sets of dependencies to different binaries. - export project(':dependency') + export(project(':dependency')) } } } ``` -```kotlin + + + +```groovy kotlin { sourceSets { macosMain.dependencies { // Will be exported. - api(project(":dependency")) - api("org.example:exported-library:1.0") + api project(':dependency') + api 'org.example:exported-library:1.0' // Will not be exported. - api("org.example:not-exported-library:1.0") + api 'org.example:not-exported-library:1.0' } } macosX64("macos").binaries { framework { - export(project(":dependency")) - export("org.example:exported-library:1.0") + export project(':dependency') + export 'org.example:exported-library:1.0' } sharedLib { // It's possible to export different sets of dependencies to different binaries. - export(project(':dependency')) + export project(':dependency') } } } ``` + > You can export only [`api` dependencies](gradle.md#dependency-types) of the corresponding source set. @@ -253,17 +278,8 @@ only methods of `foo` are added to the output framework. You can change this behavior using the `transitiveExport` option. If set to `true`, the declarations of the library `bar` are exported as well. - - -```groovy -binaries { - framework { - export project(':dependency') - // Export transitively. - transitiveExport = true - } -} -``` + + ```kotlin binaries { @@ -275,6 +291,20 @@ binaries { } ``` + + + +```groovy +binaries { + framework { + export project(':dependency') + // Export transitively. + transitiveExport = true + } +} +``` + + For example, assume that you write several modules in Kotlin and then want to access them from Swift. Since usage of @@ -292,64 +322,69 @@ framework on both 32-bit and 64-bit devices. > {type="note"} - + + -```groovy +```kotlin import org.jetbrains.kotlin.gradle.tasks.FatFrameworkTask kotlin { // Create and configure the targets. - targets { - iosArm32("ios32") - iosArm64("ios64") - configure([ios32, ios64]) { - binaries.framework { - baseName = "my_framework" - } + val ios32 = iosArm32("ios32") + val ios64 = iosArm64("ios64") + configure(listOf(ios32, ios64)) { + binaries.framework { + baseName = "my_framework" } } - // Create a task building a fat framework. - tasks.register("debugFatFramework", FatFrameworkTask) { + // Create a task to build a fat framework. + tasks.register("debugFatFramework") { // The fat framework must have the same base name as the initial frameworks. baseName = "my_framework" // The default destination directory is "/fat-framework". - destinationDir = file("$buildDir/fat-framework/debug") + destinationDir = buildDir.resolve("fat-framework/debug") // Specify the frameworks to be merged. from( - targets.ios32.binaries.getFramework("DEBUG"), - targets.ios64.binaries.getFramework("DEBUG") + ios32.binaries.getFramework("DEBUG"), + ios64.binaries.getFramework("DEBUG") ) } } ``` -```kotlin + + + +```groovy import org.jetbrains.kotlin.gradle.tasks.FatFrameworkTask kotlin { // Create and configure the targets. - val ios32 = iosArm32("ios32") - val ios64 = iosArm64("ios64") - configure(listOf(ios32, ios64)) { - binaries.framework { - baseName = "my_framework" + targets { + iosArm32("ios32") + iosArm64("ios64") + configure([ios32, ios64]) { + binaries.framework { + baseName = "my_framework" + } } } - // Create a task to build a fat framework. - tasks.register("debugFatFramework") { + // Create a task building a fat framework. + tasks.register("debugFatFramework", FatFrameworkTask) { // The fat framework must have the same base name as the initial frameworks. baseName = "my_framework" // The default destination directory is "/fat-framework". - destinationDir = buildDir.resolve("fat-framework/debug") + destinationDir = file("$buildDir/fat-framework/debug") // Specify the frameworks to be merged. from( - ios32.binaries.getFramework("DEBUG"), - ios64.binaries.getFramework("DEBUG") + targets.ios32.binaries.getFramework("DEBUG"), + targets.ios64.binaries.getFramework("DEBUG") ) } } ``` + ## Build XCFrameworks @@ -357,7 +392,8 @@ kotlin { All Kotlin Multiplatform projects can use XCFrameworks as an output to gather logic for all the target platforms and architectures in a single bundle. Unlike [universal (fat) frameworks](#build-universal-frameworks), you don't need to remove all unnecessary architectures before publishing the application to the App Store. - + + ```kotlin import org.jetbrains.kotlin.gradle.plugin.mpp.apple.XCFramework @@ -390,6 +426,9 @@ kotlin { } ``` + + + ```groovy import org.jetbrains.kotlin.gradle.plugin.mpp.apple.XCFrameworkConfig @@ -421,6 +460,7 @@ kotlin { } ``` + When you declare XCFrameworks, Kotlin Gradle plugin will register three Gradle tasks: diff --git a/docs/topics/mpp/mpp-configure-compilations.md b/docs/topics/mpp/mpp-configure-compilations.md index 39a551d3805..6dd56a28369 100644 --- a/docs/topics/mpp/mpp-configure-compilations.md +++ b/docs/topics/mpp/mpp-configure-compilations.md @@ -38,11 +38,12 @@ kotlin { ## Configure compilations for one target - + + -```groovy +```kotlin kotlin { - jvm().compilations.all { + targets.jvm.compilations.all { kotlinOptions { sourceMap = true metaInfo = true @@ -51,9 +52,12 @@ kotlin { } ``` -```kotlin + + + +```groovy kotlin { - targets.jvm.compilations.all { + jvm().compilations.all { kotlinOptions { sourceMap = true metaInfo = true @@ -62,21 +66,13 @@ kotlin { } ``` + ## Configure one compilation - - -```groovy -kotlin { - jvm().compilations.main { - kotlinOptions { - jvmTarget = "1.8" - } - } -} -``` + + ```kotlin kotlin { @@ -90,6 +86,20 @@ kotlin { } ``` + + + +```groovy +kotlin { + jvm().compilations.main { + kotlinOptions { + jvmTarget = "1.8" + } + } +} +``` + + ## Create a custom compilation @@ -105,35 +115,8 @@ collection. > {type="note"} - - -```groovy -kotlin { - jvm() { - compilations.create('integrationTest') { - defaultSourceSet { - dependencies { - def main = compilations.main - // Compile against the main compilation's compile classpath and outputs: - implementation(main.compileDependencyFiles + main.output.classesDirs) - implementation kotlin('test-junit') - /* ... */ - } - } - - // Create a test task to run the tests produced by this compilation: - tasks.register('jvmIntegrationTest', Test) { - // Run the tests with the classpath containing the compile dependencies (including 'main'), - // runtime dependencies, and the outputs of this compilation: - classpath = compileDependencyFiles + runtimeDependencyFiles + output.allOutputs - - // Run only the tests from this compilation's outputs: - testClassesDirs = output.classesDirs - } - } - } -} -``` + + ```kotlin kotlin { @@ -166,6 +149,38 @@ kotlin { } ``` + + + +```groovy +kotlin { + jvm() { + compilations.create('integrationTest') { + defaultSourceSet { + dependencies { + def main = compilations.main + // Compile against the main compilation's compile classpath and outputs: + implementation(main.compileDependencyFiles + main.output.classesDirs) + implementation kotlin('test-junit') + /* ... */ + } + } + + // Create a test task to run the tests produced by this compilation: + tasks.register('jvmIntegrationTest', Test) { + // Run the tests with the classpath containing the compile dependencies (including 'main'), + // runtime dependencies, and the outputs of this compilation: + classpath = compileDependencyFiles + runtimeDependencyFiles + output.allOutputs + + // Run only the tests from this compilation's outputs: + testClassesDirs = output.classesDirs + } + } + } +} +``` + + You also need to create a custom compilation in other cases, for example, if you want to combine compilations for different @@ -221,45 +236,12 @@ compilation. A compilation can interact with several native libraries. Configure interoperability in the `cinterops` block of the compilation with [available parameters](mpp-dsl-reference.md#cinterops). - - -```groovy -kotlin { - linuxX64 { // Replace with a target you need. - compilations.main { - cinterops { - myInterop { - // Def-file describing the native API. - // The default path is src/nativeInterop/cinterop/.def - defFile 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 eqivalent of the -I compiler option). - includeDirs.allHeaders("path1", "path2") - - // Additional directories to search headers listed in the 'headerFilter' def-file option. - // -headerFilterAdditionalSearchPrefix command line option equivalent. - includeDirs.headerFilterOnly("path1", "path2") - - // A shortcut for includeDirs.allHeaders. - includeDirs("include/directory", "another/directory") - } - - anotherInterop { /* ... */ } - } - } - } -} -``` + + ```kotlin kotlin { - linuxX64 { // Replace with a target you need. + linuxX64 { // Replace with a target you need. compilations.getByName("main") { val myInterop by cinterops.creating { // Def-file describing the native API. @@ -289,9 +271,46 @@ kotlin { } } } +``` + + + +```groovy +kotlin { + linuxX64 { // Replace with a target you need. + compilations.main { + cinterops { + myInterop { + // Def-file describing the native API. + // The default path is src/nativeInterop/cinterop/.def + defFile 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 eqivalent of the -I compiler option). + includeDirs.allHeaders("path1", "path2") + + // Additional directories to search headers listed in the 'headerFilter' def-file option. + // -headerFilterAdditionalSearchPrefix command line option equivalent. + includeDirs.headerFilterOnly("path1", "path2") + + // A shortcut for includeDirs.allHeaders. + includeDirs("include/directory", "another/directory") + } + + anotherInterop { /* ... */ } + } + } + } +} ``` + ## Compilation for Android diff --git a/docs/topics/mpp/mpp-discover-project.md b/docs/topics/mpp/mpp-discover-project.md index 6aa016cd2c6..b302cbf2891 100644 --- a/docs/topics/mpp/mpp-discover-project.md +++ b/docs/topics/mpp/mpp-discover-project.md @@ -18,20 +18,25 @@ You can also apply it manually. > {type="note"} - + + -```groovy +```kotlin plugins { - id 'org.jetbrains.kotlin.multiplatform' version '%kotlinVersion%' + kotlin("multiplatform") version "%kotlinVersion%" } ``` -```kotlin + + + +```groovy plugins { - kotlin("multiplatform") version "%kotlinVersion%" + id 'org.jetbrains.kotlin.multiplatform' version '%kotlinVersion%' } ``` + The `kotlin-multiplatform` plugin configures the project for creating an application or library to work on multiple platforms @@ -76,20 +81,8 @@ default source sets for the `main` and `test` compilations of the common code an Source sets are added to the `sourceSets` block of the top-level `kotlin` block. - - -```groovy -kotlin { - sourceSets { - commonMain { /* ... */} - commonTest { /* ... */} - jvmMain { /* ... */} - jvmTest { /* ... */ } - jsMain { /* ... */} - jsTest { /* ... */} - } -} -``` + + ```kotlin kotlin { @@ -104,6 +97,23 @@ kotlin { } ``` + + + +```groovy +kotlin { + sourceSets { + commonMain { /* ... */} + commonTest { /* ... */} + jvmMain { /* ... */} + jvmTest { /* ... */ } + jsMain { /* ... */} + jsTest { /* ... */} + } +} +``` + + Source sets form a hierarchy, which is used for sharing the common code. In a source set shared among several targets, diff --git a/docs/topics/mpp/mpp-dsl-reference.md b/docs/topics/mpp/mpp-dsl-reference.md index eea99459d4b..8feb7bd27a5 100644 --- a/docs/topics/mpp/mpp-dsl-reference.md +++ b/docs/topics/mpp/mpp-dsl-reference.md @@ -14,20 +14,25 @@ The fully qualified name of the Kotlin Multiplatform Gradle plugin is `org.jetbr 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 %kotlinVersion%. - + + -```groovy +```kotlin plugins { - id 'org.jetbrains.kotlin.multiplatform' version '%kotlinVersion%' + kotlin("multiplatform") version "%kotlinVersion%" } ``` -```kotlin + + + +```groovy plugins { - kotlin("multiplatform") version "%kotlinVersion%" + id 'org.jetbrains.kotlin.multiplatform' version '%kotlinVersion%' } ``` + ## Top-level blocks @@ -237,22 +242,23 @@ For binaries configuration, the following parameters are available: |`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.| - + + -```groovy +```kotlin binaries { - executable('my_executable', [RELEASE]) { + executable("my_executable", listOf(RELEASE)) { // Build a binary on the basis of the test compilation. - compilation = compilations.test + compilation = compilations["test"] // Custom command line options for the linker. - linkerOpts = ['-L/lib/search/path', '-L/another/search/path', '-lmylib'] + linkerOpts = mutableListOf("-L/lib/search/path", "-L/another/search/path", "-lmylib") // Base name for the output file. - baseName = 'foo' + baseName = "foo" // Custom entry point function. - entryPoint = 'org.example.main' + entryPoint = "org.example.main" // Accessing the output file. println("Executable path: ${outputFile.absolutePath}") @@ -265,27 +271,30 @@ binaries { runTask?.dependsOn(prepareForRun) } - framework('my_framework' [RELEASE]) { + framework("my_framework" listOf(RELEASE)) { // Include a static library instead of a dynamic one into the framework. isStatic = true } } ``` -```kotlin + + + +```groovy binaries { - executable("my_executable", listOf(RELEASE)) { + executable('my_executable', [RELEASE]) { // Build a binary on the basis of the test compilation. - compilation = compilations["test"] + compilation = compilations.test // Custom command line options for the linker. - linkerOpts = mutableListOf("-L/lib/search/path", "-L/another/search/path", "-lmylib") + linkerOpts = ['-L/lib/search/path', '-L/another/search/path', '-lmylib'] // Base name for the output file. - baseName = "foo" + baseName = 'foo' // Custom entry point function. - entryPoint = "org.example.main" + entryPoint = 'org.example.main' // Accessing the output file. println("Executable path: ${outputFile.absolutePath}") @@ -298,13 +307,14 @@ binaries { runTask?.dependsOn(prepareForRun) } - framework("my_framework" listOf(RELEASE)) { + framework('my_framework' [RELEASE]) { // Include a static library instead of a dynamic one into the framework. isStatic = true } } ``` + Learn more about [building native binaries](mpp-build-native-binaries.md). @@ -323,7 +333,39 @@ To provide an interop with a library, add an entry to `cinterops` and define its Learn more how to [configure interop with native languages](mpp-configure-compilations.md#configure-interop-with-native-languages). - + + + +```kotlin +kotlin { + linuxX64 { // Replace with a target you need. + compilations.getByName("main") { + val myInterop by cinterops.creating { + // Def-file describing the native API. + // The default path is src/nativeInterop/cinterop/.def + defFile(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 compiler option). + includeDirs.allHeaders("path1", "path2") + + // A shortcut for includeDirs.allHeaders. + includeDirs("include/directory", "another/directory") + } + + val anotherInterop by cinterops.creating { /* ... */ } + } + } +} +``` + + + ```groovy kotlin { @@ -355,35 +397,7 @@ kotlin { } ``` -```kotlin -kotlin { - linuxX64 { // Replace with a target you need. - compilations.getByName("main") { - val myInterop by cinterops.creating { - // Def-file describing the native API. - // The default path is src/nativeInterop/cinterop/.def - defFile(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 compiler option). - includeDirs.allHeaders("path1", "path2") - - // A shortcut for includeDirs.allHeaders. - includeDirs("include/directory", "another/directory") - } - - val anotherInterop by cinterops.creating { /* ... */ } - } - } -} - -``` - + ### Android targets @@ -432,7 +446,19 @@ Available predefined source sets are the following: With Kotlin Gradle DSL, the sections of predefined source sets should be marked `by getting`. - + + + +```kotlin +kotlin { + sourceSets { + val commonMain by getting { /* ... */ } + } +} +``` + + + ```groovy kotlin { @@ -442,14 +468,7 @@ kotlin { } ``` -```kotlin -kotlin { - sourceSets { - val commonMain by getting { /* ... */ } - } -} -``` - + Learn more about [source sets](mpp-discover-project.md#source-sets). @@ -460,24 +479,29 @@ 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 `by creating`. - + + -```groovy +```kotlin kotlin { sourceSets { - myMain { /* ... */ } // create or configure a source set by the name 'myMain' + val myMain by creating { /* ... */ } // create a new source set by the name 'MyMain' } } -``` +``` -```kotlin + + + +```groovy kotlin { sourceSets { - val myMain by creating { /* ... */ } // create a new source set by the name 'MyMain' + 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, @@ -495,38 +519,43 @@ Configurations of source sets are stored inside the corresponding blocks of `sou |`dependencies`|[Dependencies](#dependencies) of the source set.| |`languageSettings`|[Language settings](mpp-dsl-reference.md#language-settings) applied to the source set.| - + + -```groovy +```kotlin kotlin { sourceSets { - commonMain { - kotlin.srcDir('src') - resources.srcDir('res') + val commonMain by getting { + kotlin.srcDir("src") + resources.srcDir("res") dependencies { /* ... */ - } + } } } } -``` +``` -```kotlin + + + +```groovy kotlin { sourceSets { - val commonMain by getting { - kotlin.srcDir("src") - resources.srcDir("res") + commonMain { + kotlin.srcDir('src') + resources.srcDir('res') dependencies { /* ... */ - } + } } } } -``` +``` + ## Compilations @@ -549,16 +578,8 @@ Available predefined compilations are the following: |`main`|Compilation for production sources.| |`test`|Compilation for tests.| - - -```groovy -kotlin { - jvm { - compilations.main.output // get the main compilation output - compilations.test.runtimeDependencyFiles // get the test runtime classpath - } -} -``` + + ```kotlin kotlin { @@ -572,6 +593,19 @@ kotlin { } ``` + + + +```groovy +kotlin { + jvm { + compilations.main.output // get the main compilation output + compilations.test.runtimeDependencyFiles // get the test runtime classpath + } +} +``` + + ### Custom compilations @@ -582,26 +616,8 @@ If using Kotlin Gradle DSL, mark custom compilations `by creating`. Learn more about creating a [custom compilation](mpp-configure-compilations.md#create-a-custom-compilation). - - -```groovy -kotlin { - jvm() { - compilations.create('integrationTest') { - defaultSourceSet { - dependencies { - /* ... */ - } - } - - // Create a test task to run the tests produced by this compilation: - tasks.register('jvmIntegrationTest', Test) { - /* ... */ - } - } - } -} -``` + + ```kotlin kotlin { @@ -624,6 +640,29 @@ kotlin { } ``` + + + +```groovy +kotlin { + jvm() { + compilations.create('integrationTest') { + defaultSourceSet { + dependencies { + /* ... */ + } + } + + // Create a test task to run the tests produced by this compilation: + tasks.register('jvmIntegrationTest', Test) { + /* ... */ + } + } + } +} +``` + + ### Compilation parameters @@ -643,19 +682,23 @@ A compilation has the following parameters: |`compileDependencyFiles`|Compile-time dependency files (classpath) of the compilation.| |`runtimeDependencyFiles`|Runtime dependency files (classpath) of the compilation.| - + + -```groovy +```kotlin kotlin { jvm { - compilations.main.kotlinOptions { - // Setup the Kotlin compiler options for the 'main' compilation: - jvmTarget = "1.8" + val main by compilations.getting { + kotlinOptions { + // Setup the Kotlin compiler options for the 'main' compilation: + jvmTarget = "1.8" + } + + compileKotlinTask // get the Kotlin task 'compileKotlinJvm' + output // get the main compilation output } - compilations.main.compileKotlinTask // get the Kotlin task 'compileKotlinJvm' - compilations.main.output // get the main compilation output - compilations.test.runtimeDependencyFiles // get the test runtime classpath + compilations["test"].runtimeDependencyFiles // get the test runtime classpath } // Configure all compilations of all targets: @@ -669,20 +712,20 @@ kotlin { } ``` -```kotlin + + + +```groovy kotlin { jvm { - val main by compilations.getting { - kotlinOptions { - // Setup the Kotlin compiler options for the 'main' compilation: - jvmTarget = "1.8" - } - - compileKotlinTask // get the Kotlin task 'compileKotlinJvm' - output // get the main compilation output + compilations.main.kotlinOptions { + // Setup the Kotlin compiler options for the 'main' compilation: + jvmTarget = "1.8" } - compilations["test"].runtimeDependencyFiles // get the test runtime classpath + 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: @@ -696,6 +739,7 @@ kotlin { } ``` + ## Dependencies @@ -713,42 +757,47 @@ There are four types of dependencies: |`compileOnly`|Dependencies used only for compilation of the current module.| |`runtimeOnly`|Dependencies available at runtime but not visible during compilation of any module.| - + + -```groovy +```kotlin kotlin { sourceSets { - commonMain { + val commonMain by getting { dependencies { - api 'com.example:foo-metadata:1.0' + api("com.example:foo-metadata:1.0") } } - jvm6Main { + val jvm6Main by getting { dependencies { - implementation 'com.example:foo-jvm6:1.0' + implementation("com.example:foo-jvm6:1.0") } } } } ``` -```kotlin + + + +```groovy kotlin { sourceSets { - val commonMain by getting { + commonMain { dependencies { - api("com.example:foo-metadata:1.0") + api 'com.example:foo-metadata:1.0' } } - val jvm6Main by getting { + jvm6Main { dependencies { - implementation("com.example:foo-jvm6:1.0") + implementation 'com.example:foo-jvm6:1.0' } } } } ``` + Additionally, source sets can depend on each other and form a hierarchy. In this case, the [dependsOn()](#source-set-parameters) relation is used. @@ -756,22 +805,27 @@ Additionally, source sets can depend on each other and form a hierarchy. In this 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 ``, for example, `commonMainApi`. - + + -```groovy +```kotlin dependencies { - commonMainApi 'com.example:foo-common:1.0' - jvm6MainApi 'com.example:foo-jvm6:1.0' + "commonMainApi"("com.example:foo-common:1.0") + "jvm6MainApi"("com.example:foo-jvm6:1.0") } ``` -```kotlin + + + +```groovy dependencies { - "commonMainApi"("com.example:foo-common:1.0") - "jvm6MainApi"("com.example:foo-jvm6:1.0") + commonMainApi 'com.example:foo-common:1.0' + jvm6MainApi 'com.example:foo-jvm6:1.0' } ``` + ## Language settings @@ -786,34 +840,39 @@ The `languageSettings` block of a source set defines certain aspects of project |`useExperimentalAnnotation`|Allows using the specified [opt-in annotation](opt-in-requirements.md).| |`progressiveMode`|Enables the [progressive mode](whatsnew13.md#progressive-mode).| - + + -```groovy +```kotlin kotlin { sourceSets.all { - languageSettings { - languageVersion = '1.4' // possible values: '1.0', '1.1', '1.2', '1.3', '1.4' - apiVersion = '1.4' // possible values: '1.0', '1.1', '1.2', '1.3', '1.4' - enableLanguageFeature('InlineClasses') // language feature name - useExperimentalAnnotation('kotlin.ExperimentalUnsignedTypes') // annotation FQ-name + languageSettings.apply { + languageVersion = "1.4" // possible values: "1.0", "1.1", "1.2", "1.3", "1.4" + apiVersion = "1.4" // possible values: "1.0", "1.1", "1.2", "1.3", "1.4" + enableLanguageFeature("InlineClasses") // language feature name + useExperimentalAnnotation("kotlin.ExperimentalUnsignedTypes") // annotation FQ-name progressiveMode = true // false by default } } } ``` -```kotlin + + + +```groovy kotlin { sourceSets.all { - languageSettings.apply { - languageVersion = "1.4" // possible values: "1.0", "1.1", "1.2", "1.3", "1.4" - apiVersion = "1.4" // possible values: "1.0", "1.1", "1.2", "1.3", "1.4" - enableLanguageFeature("InlineClasses") // language feature name - useExperimentalAnnotation("kotlin.ExperimentalUnsignedTypes") // annotation FQ-name + languageSettings { + languageVersion = '1.4' // possible values: '1.0', '1.1', '1.2', '1.3', '1.4' + apiVersion = '1.4' // possible values: '1.0', '1.1', '1.2', '1.3', '1.4' + enableLanguageFeature('InlineClasses') // language feature name + useExperimentalAnnotation('kotlin.ExperimentalUnsignedTypes') // annotation FQ-name progressiveMode = true // false by default } } } ``` + diff --git a/docs/topics/mpp/mpp-publish-lib.md b/docs/topics/mpp/mpp-publish-lib.md index 7f34d2a5b4f..8a13f7b06cd 100644 --- a/docs/topics/mpp/mpp-publish-lib.md +++ b/docs/topics/mpp/mpp-publish-lib.md @@ -56,20 +56,22 @@ platform. Alternatively, you can pass the flag from an external source, for exam This simplified example ensures that publications are only uploaded when `isMainHost=true` is passed. This means that a publication that can be published from multiple platforms will be published only once – from the main host. - + + -```groovy +```kotlin kotlin { jvm() js() mingwX64() linuxX64() - def publicationsFromMainHost = - [jvm(), js()].collect { it.name } + "kotlinMultiplatform" + val publicationsFromMainHost = + listOf(jvm(), js()).map { it.name } + "kotlinMultiplatform" publishing { publications { - matching { it.name in publicationsFromMainHost }.all { targetPublication -> - tasks.withType(AbstractPublishToMaven) + matching { it.name in publicationsFromMainHost }.all { + val targetPublication = this@all + tasks.withType() .matching { it.publication == targetPublication } .configureEach { onlyIf { findProperty("isMainHost") == "true" } } } @@ -78,19 +80,21 @@ kotlin { } ``` -```kotlin + + + +```groovy kotlin { jvm() js() mingwX64() linuxX64() - val publicationsFromMainHost = - listOf(jvm(), js()).map { it.name } + "kotlinMultiplatform" + def publicationsFromMainHost = + [jvm(), js()].collect { it.name } + "kotlinMultiplatform" publishing { publications { - matching { it.name in publicationsFromMainHost }.all { - val targetPublication = this@all - tasks.withType() + matching { it.name in publicationsFromMainHost }.all { targetPublication -> + tasks.withType(AbstractPublishToMaven) .matching { it.publication == targetPublication } .configureEach { onlyIf { findProperty("isMainHost") == "true" } } } @@ -99,6 +103,7 @@ kotlin { } ``` + By default, each publication includes a sources JAR that contains the sources used by the main compilation of the target. diff --git a/docs/topics/mpp/mpp-set-up-targets.md b/docs/topics/mpp/mpp-set-up-targets.md index 82c9ff99eb1..402ec62202f 100644 --- a/docs/topics/mpp/mpp-set-up-targets.md +++ b/docs/topics/mpp/mpp-set-up-targets.md @@ -30,34 +30,39 @@ during dependency resolution. For example, consider a testing library that supports both JUnit and TestNG in the two targets. The library author needs to add an attribute to both targets as follows: - + + -```groovy -def testFrameworkAttribute = Attribute.of('com.example.testFramework', String) +```kotlin +val testFrameworkAttribute = Attribute.of("com.example.testFramework", String::class.java) kotlin { - jvm('junit') { - attributes.attribute(testFrameworkAttribute, 'junit') + jvm("junit") { + attributes.attribute(testFrameworkAttribute, "junit") } - jvm('testng') { - attributes.attribute(testFrameworkAttribute, 'testng') + jvm("testng") { + attributes.attribute(testFrameworkAttribute, "testng") } } ``` -```kotlin -val testFrameworkAttribute = Attribute.of("com.example.testFramework", String::class.java) + + + +```groovy +def testFrameworkAttribute = Attribute.of('com.example.testFramework', String) kotlin { - jvm("junit") { - attributes.attribute(testFrameworkAttribute, "junit") + jvm('junit') { + attributes.attribute(testFrameworkAttribute, 'junit') } - jvm("testng") { - attributes.attribute(testFrameworkAttribute, "testng") + jvm('testng') { + attributes.attribute(testFrameworkAttribute, 'testng') } } ``` + The consumer has to add the attribute to a single target where the ambiguity arises. \ No newline at end of file diff --git a/docs/topics/mpp/mpp-share-on-platforms.md b/docs/topics/mpp/mpp-share-on-platforms.md index cc5265e1bc4..f3708ae972e 100644 --- a/docs/topics/mpp/mpp-share-on-platforms.md +++ b/docs/topics/mpp/mpp-share-on-platforms.md @@ -81,35 +81,40 @@ The `kotlin-multiplatform` plugin provides target shortcuts for creating structu All shortcuts create similar hierarchical structures in the code. For example, the `ios` shortcut creates the following hierarchical structure: - + + -```groovy +```kotlin kotlin { sourceSets{ - iosMain { + val commonMain by sourceSets.getting + val iosX64Main by sourceSets.getting + val iosArm64Main by sourceSets.getting + val iosMain by sourceSets.creating { dependsOn(commonMain) - iosX64Main.dependsOn(it) - iosArm64Main.dependsOn(it) + iosX64Main.dependsOn(this) + iosArm64Main.dependsOn(this) } } } ``` -```kotlin + + + +```groovy kotlin { sourceSets{ - val commonMain by sourceSets.getting - val iosX64Main by sourceSets.getting - val iosArm64Main by sourceSets.getting - val iosMain by sourceSets.creating { + iosMain { dependsOn(commonMain) - iosX64Main.dependsOn(this) - iosArm64Main.dependsOn(this) + iosX64Main.dependsOn(it) + iosArm64Main.dependsOn(it) } } } ``` + #### Target shortcuts and ARM64 (Apple Silicon) simulators @@ -121,7 +126,28 @@ the project for an Apple Silicon simulator, adjust the build script the followin 1. Add the `*SimulatorArm64` simulator target you need. 2. Connect the simulator target with the shortcut using the source set dependencies (`dependsOn`). - + + + +```kotlin +kotlin { + ios() + // Add the ARM64 simulator target + iosSimulatorArm64() + + val iosMain by sourceSets.getting + val iosTest by sourceSets.getting + val iosSimulatorArm64Main by sourceSets.getting + val iosSimulatorArm64Test by sourceSets.getting + + // Set up dependencies between the source sets + iosSimulatorArm64Main.dependsOn(iosMain) + iosSimulatorArm64Test.dependsOn(iosTest) +} +``` + + + ```groovy kotlin { @@ -142,23 +168,7 @@ kotlin { } ``` -```kotlin -kotlin { - ios() - // Add the ARM64 simulator target - iosSimulatorArm64() - - val iosMain by sourceSets.getting - val iosTest by sourceSets.getting - val iosSimulatorArm64Main by sourceSets.getting - val iosSimulatorArm64Test by sourceSets.getting - - // Set up dependencies between the source sets - iosSimulatorArm64Main.dependsOn(iosMain) - iosSimulatorArm64Test.dependsOn(iosTest) -} -``` - + @@ -175,46 +185,51 @@ For example, if you want to share code among native Linux, Windows, and macOS ta 1. Add the intermediate source set `desktopMain` that holds the shared logic for these targets. 2. Specify the hierarchy of source sets using the `dependsOn` relation. - + + -```groovy -kotlin { +```kotlin +kotlin{ sourceSets { - desktopMain { + val desktopMain by creating { dependsOn(commonMain) } - linuxX64Main { + val linuxX64Main by getting { dependsOn(desktopMain) } - mingwX64Main { + val mingwX64Main by getting { dependsOn(desktopMain) } - macosX64Main { + val macosX64Main by getting { dependsOn(desktopMain) } } } ``` -```kotlin -kotlin{ + + + +```groovy +kotlin { sourceSets { - val desktopMain by creating { + desktopMain { dependsOn(commonMain) } - val linuxX64Main by getting { + linuxX64Main { dependsOn(desktopMain) } - val mingwX64Main by getting { + mingwX64Main { dependsOn(desktopMain) } - val macosX64Main by getting { + macosX64Main { dependsOn(desktopMain) } } } ``` + You can have a shared source set for the following combinations of targets: diff --git a/docs/topics/mpp/multiplatform-library.md b/docs/topics/mpp/multiplatform-library.md index 12c10dccdde..c6c96548743 100644 --- a/docs/topics/mpp/multiplatform-library.md +++ b/docs/topics/mpp/multiplatform-library.md @@ -283,17 +283,8 @@ To publish your library, use the [`maven-publish` Gradle plugin](https://docs.gr 1. In the `build.gradle(.kts)` file, apply the `maven-publish` plugin and specify the group and version of your library: - - -```groovy -plugins { - id 'org.jetbrains.kotlin.multiplatform' version '%kotlinVersion%' - id 'maven-publish' -} - -group = 'org.jetbrains.base64' -version = '1.0.0' -``` + + ```kotlin plugins { @@ -305,6 +296,20 @@ group = "org.jetbrains.base64" version = "1.0.0" ``` + + + +```groovy +plugins { + id 'org.jetbrains.kotlin.multiplatform' version '%kotlinVersion%' + id 'maven-publish' +} + +group = 'org.jetbrains.base64' +version = '1.0.0' +``` + + 2. In the Terminal, run the `publishToMavenLocal` Gradle task to publish your library to your local Maven repository: @@ -326,9 +331,10 @@ Now you can add your library to other multiplatform projects as a dependency. Add the `mavenLocal()` repository and add a dependency on your library to the `build.gradle(.kts)` file. - + + -```groovy +```kotlin repositories { mavenCentral() mavenLocal() @@ -336,16 +342,19 @@ repositories { kotlin { sourceSets { - commonMain { + val commonMain by getting { dependencies { - implementation 'org.jetbrains.base64:Base64:1.0.0' + implementation("org.jetbrains.base64:Base64:1.0.0") } } } } ``` -```kotlin + + + +```groovy repositories { mavenCentral() mavenLocal() @@ -353,15 +362,16 @@ repositories { kotlin { sourceSets { - val commonMain by getting { + commonMain { dependencies { - implementation("org.jetbrains.base64:Base64:1.0.0") + implementation 'org.jetbrains.base64:Base64:1.0.0' } } } } ``` + ## Summary diff --git a/docs/topics/native/apple-framework.md b/docs/topics/native/apple-framework.md index a762436444f..eb3b449082e 100644 --- a/docs/topics/native/apple-framework.md +++ b/docs/topics/native/apple-framework.md @@ -72,11 +72,12 @@ the missing directories will have to be created before any new files can be adde Use the following `build.gradle(.kts)` Gradle build file: - + + -```groovy +```kotlin plugins { - id 'org.jetbrains.kotlin.multiplatform' version '%kotlinVersion%' + kotlin("multiplatform") version "%kotlinVersion%" } repositories { @@ -93,15 +94,18 @@ kotlin { } } -wrapper { +tasks.wrapper { gradleVersion = "%gradleVersion%" - distributionType = "ALL" + distributionType = Wrapper.DistributionType.ALL } ``` -```kotlin + + + +```groovy plugins { - kotlin("multiplatform") version "%kotlinVersion%" + id 'org.jetbrains.kotlin.multiplatform' version '%kotlinVersion%' } repositories { @@ -118,12 +122,13 @@ kotlin { } } -tasks.wrapper { +wrapper { gradleVersion = "%gradleVersion%" - distributionType = Wrapper.DistributionType.ALL + distributionType = "ALL" } ``` + Move the sources file into the `src/nativeMain/kotlin` folder under diff --git a/docs/topics/native/mapping-function-pointers-from-c.md b/docs/topics/native/mapping-function-pointers-from-c.md index d1e6c732bda..e9eb95da4cc 100644 --- a/docs/topics/native/mapping-function-pointers-from-c.md +++ b/docs/topics/native/mapping-function-pointers-from-c.md @@ -70,11 +70,12 @@ the missing directories will have to be created before any new files can be adde Use the following `build.gradle(.kts)` Gradle build file: - + + -```groovy +```kotlin plugins { - id 'org.jetbrains.kotlin.multiplatform' version '%kotlinVersion%' + kotlin("multiplatform") version "%kotlinVersion%" } repositories { @@ -82,13 +83,12 @@ repositories { } kotlin { - linuxX64('native') { // on Linux + linuxX64("native") { // on Linux // macosX64("native") { // on x86_64 macOS - // macosArm64("native") { // on Apple Silicon macOS - // mingwX64('native') { //on Windows - compilations.main.cinterops { - interop - } + // macosArm64("native") { // on Apple Silicon macOS + // mingwX64("native") { // on Windows + val main by compilations.getting + val interop by main.cinterops.creating binaries { executable() @@ -96,15 +96,18 @@ kotlin { } } -wrapper { - gradleVersion = '%gradleVersion%' - distributionType = 'BIN' +tasks.wrapper { + gradleVersion = "%gradleVersion%" + distributionType = Wrapper.DistributionType.BIN } ``` -```kotlin + + + +```groovy plugins { - kotlin("multiplatform") version "%kotlinVersion%" + id 'org.jetbrains.kotlin.multiplatform' version '%kotlinVersion%' } repositories { @@ -112,12 +115,13 @@ repositories { } kotlin { - linuxX64("native") { // on Linux + linuxX64('native') { // on Linux // macosX64("native") { // on x86_64 macOS - // macosArm64("native") { // on Apple Silicon macOS - // mingwX64("native") { // on Windows - val main by compilations.getting - val interop by main.cinterops.creating + // macosArm64("native") { // on Apple Silicon macOS + // mingwX64('native') { // on Windows + compilations.main.cinterops { + interop + } binaries { executable() @@ -125,12 +129,13 @@ kotlin { } } -tasks.wrapper { - gradleVersion = "%gradleVersion%" - distributionType = Wrapper.DistributionType.BIN +wrapper { + gradleVersion = '%gradleVersion%' + distributionType = 'BIN' } ``` + The project file configures the C interop as an additional step of the build. diff --git a/docs/topics/native/mapping-primitive-data-types-from-c.md b/docs/topics/native/mapping-primitive-data-types-from-c.md index 6d21d849bec..a56290e90d0 100644 --- a/docs/topics/native/mapping-primitive-data-types-from-c.md +++ b/docs/topics/native/mapping-primitive-data-types-from-c.md @@ -101,11 +101,12 @@ the missing directories will have to be created before any new files can be adde Use the following `build.gradle(.kts)` Gradle build file: - + + -```groovy +```kotlin plugins { - id 'org.jetbrains.kotlin.multiplatform' version '%kotlinVersion%' + kotlin("multiplatform") version "%kotlinVersion%" } repositories { @@ -113,13 +114,12 @@ repositories { } kotlin { - linuxX64('native') { // on Linux + linuxX64("native") { // on Linux // macosX64("native") { // on x86_64 macOS // macosArm64("native") { // on Apple Silicon macOS - // mingwX64('native') { //on Windows - compilations.main.cinterops { - interop - } + // mingwX64("native") { // on Windows + val main by compilations.getting + val interop by main.cinterops.creating binaries { executable() @@ -127,15 +127,18 @@ kotlin { } } -wrapper { - gradleVersion = '%gradleVersion%' - distributionType = 'BIN' +tasks.wrapper { + gradleVersion = "%gradleVersion%" + distributionType = Wrapper.DistributionType.BIN } ``` -```kotlin + + + +```groovy plugins { - kotlin("multiplatform") version "%kotlinVersion%" + id 'org.jetbrains.kotlin.multiplatform' version '%kotlinVersion%' } repositories { @@ -143,12 +146,13 @@ repositories { } kotlin { - linuxX64("native") { // on Linux + linuxX64('native') { // on Linux // macosX64("native") { // on x86_64 macOS // macosArm64("native") { // on Apple Silicon macOS - // mingwX64("native") { // on Windows - val main by compilations.getting - val interop by main.cinterops.creating + // mingwX64('native') { // on Windows + compilations.main.cinterops { + interop + } binaries { executable() @@ -156,12 +160,13 @@ kotlin { } } -tasks.wrapper { - gradleVersion = "%gradleVersion%" - distributionType = Wrapper.DistributionType.BIN +wrapper { + gradleVersion = '%gradleVersion%' + distributionType = 'BIN' } ``` + The project file configures the C interop as an additional step of the build. diff --git a/docs/topics/native/mapping-strings-from-c.md b/docs/topics/native/mapping-strings-from-c.md index ea94d139827..cdd0d5305b3 100644 --- a/docs/topics/native/mapping-strings-from-c.md +++ b/docs/topics/native/mapping-strings-from-c.md @@ -96,11 +96,12 @@ the missing directories will have to be created before any new files can be adde Use the following `build.gradle(.kts)` Gradle build file: - + + -```groovy +```kotlin plugins { - id 'org.jetbrains.kotlin.multiplatform' version '%kotlinVersion%' + kotlin("multiplatform") version "%kotlinVersion%" } repositories { @@ -108,13 +109,12 @@ repositories { } kotlin { - linuxX64('native') { // on Linux + linuxX64("native") { // on Linux // macosX64("native") { // on x86_64 macOS // macosArm64("native") { // on Apple Silicon macOS - // mingwX64('native') { //on Windows - compilations.main.cinterops { - interop - } + // mingwX64("native") { // on Windows + val main by compilations.getting + val interop by main.cinterops.creating binaries { executable() @@ -122,15 +122,18 @@ kotlin { } } -wrapper { - gradleVersion = '%gradleVersion%' - distributionType = 'BIN' +tasks.wrapper { + gradleVersion = "%gradleVersion%" + distributionType = Wrapper.DistributionType.BIN } ``` -```kotlin + + + +```groovy plugins { - kotlin("multiplatform") version "%kotlinVersion%" + id 'org.jetbrains.kotlin.multiplatform' version '%kotlinVersion%' } repositories { @@ -138,12 +141,13 @@ repositories { } kotlin { - linuxX64("native") { // on Linux + linuxX64('native') { // on Linux // macosX64("native") { // on x86_64 macOS // macosArm64("native") { // on Apple Silicon macOS - // mingwX64("native") { // on Windows - val main by compilations.getting - val interop by main.cinterops.creating + // mingwX64('native') { // on Windows + compilations.main.cinterops { + interop + } binaries { executable() @@ -151,12 +155,13 @@ kotlin { } } -tasks.wrapper { - gradleVersion = "%gradleVersion%" - distributionType = Wrapper.DistributionType.BIN +wrapper { + gradleVersion = '%gradleVersion%' + distributionType = 'BIN' } ``` + The project file configures the C interop as an additional step of the build. diff --git a/docs/topics/native/mapping-struct-union-types-from-c.md b/docs/topics/native/mapping-struct-union-types-from-c.md index bfa2e1d280d..ac610d524c3 100644 --- a/docs/topics/native/mapping-struct-union-types-from-c.md +++ b/docs/topics/native/mapping-struct-union-types-from-c.md @@ -69,11 +69,12 @@ the missing directories will have to be created before any new files can be adde Use the following `build.gradle(.kts)` Gradle build file: - + + -```groovy +```kotlin plugins { - id 'org.jetbrains.kotlin.multiplatform' version '%kotlinVersion%' + kotlin("multiplatform") version "%kotlinVersion%" } repositories { @@ -81,13 +82,12 @@ repositories { } kotlin { - linuxX64('native') { // on Linux + linuxX64("native") { // on Linux // macosX64("native") { // on x86_64 macOS // macosArm64("native") { // on Apple Silicon macOS - // mingwX64('native') { //on Windows - compilations.main.cinterops { - interop - } + // mingwX64("native") { // on Windows + val main by compilations.getting + val interop by main.cinterops.creating binaries { executable() @@ -95,15 +95,18 @@ kotlin { } } -wrapper { - gradleVersion = '%gradleVersion%' - distributionType = 'BIN' +tasks.wrapper { + gradleVersion = "%gradleVersion%" + distributionType = Wrapper.DistributionType.BIN } ``` -```kotlin + + + +```groovy plugins { - kotlin("multiplatform") version "%kotlinVersion%" + id 'org.jetbrains.kotlin.multiplatform' version '%kotlinVersion%' } repositories { @@ -111,12 +114,13 @@ repositories { } kotlin { - linuxX64("native") { // on Linux + linuxX64('native') { // on Linux // macosX64("native") { // on x86_64 macOS // macosArm64("native") { // on Apple Silicon macOS - // mingwX64("native") { // on Windows - val main by compilations.getting - val interop by main.cinterops.creating + // mingwX64('native') { // on Windows + compilations.main.cinterops { + interop + } binaries { executable() @@ -124,12 +128,13 @@ kotlin { } } -tasks.wrapper { - gradleVersion = "%gradleVersion%" - distributionType = Wrapper.DistributionType.BIN +wrapper { + gradleVersion = '%gradleVersion%' + distributionType = 'BIN' } ``` + The project file configures the C interop as an additional step of the build. diff --git a/docs/topics/native/native-dynamic-libraries.md b/docs/topics/native/native-dynamic-libraries.md index 3dd9e4b27cb..c8f241502cf 100644 --- a/docs/topics/native/native-dynamic-libraries.md +++ b/docs/topics/native/native-dynamic-libraries.md @@ -67,11 +67,12 @@ the missing directories will have to be created before any new files can be adde Use the following `build.gradle(.kts)` Gradle build file: - + + -```groovy +```kotlin plugins { - id 'org.jetbrains.kotlin.multiplatform' version '%kotlinVersion%' + kotlin("multiplatform") version "%kotlinVersion%" } repositories { @@ -79,28 +80,31 @@ repositories { } kotlin { - linuxX64("native") { // on Linux + linuxX64("native") { // on Linux // macosX64("native") { // on x86_64 macOS // macosArm64("native") { // on Apple Silicon macOS - // mingwX64("native") { //on Windows + // mingwX64("native") { // on Windows binaries { sharedLib { baseName = "native" // on Linux and macOS - // baseName = "libnative" //on Windows + // baseName = "libnative" // on Windows } } } } -wrapper { +tasks.wrapper { gradleVersion = "%gradleVersion%" - distributionType = "ALL" + distributionType = Wrapper.DistributionType.ALL } ``` -```kotlin + + + +```groovy plugins { - kotlin("multiplatform") version "%kotlinVersion%" + id 'org.jetbrains.kotlin.multiplatform' version '%kotlinVersion%' } repositories { @@ -108,7 +112,7 @@ repositories { } kotlin { - linuxX64("native") { // on Linux + linuxX64("native") { // on Linux // macosX64("native") { // on x86_64 macOS // macosArm64("native") { // on Apple Silicon macOS // mingwX64("native") { // on Windows @@ -121,12 +125,13 @@ kotlin { } } -tasks.wrapper { +wrapper { gradleVersion = "%gradleVersion%" - distributionType = Wrapper.DistributionType.ALL + distributionType = "ALL" } ``` + Move the sources file into the `src/nativeMain/kotlin` folder under diff --git a/docs/topics/native/native-faq.md b/docs/topics/native/native-faq.md index d2c760ed083..46d969c55c9 100644 --- a/docs/topics/native/native-faq.md +++ b/docs/topics/native/native-faq.md @@ -55,28 +55,33 @@ or set it via the `JAVA_OPTS` environment variable. Use the `-module-name` compiler option or matching Gradle DSL statement. - + + -```groovy +```kotlin kotlin { iosArm64("myapp") { binaries.framework { - freeCompilerArgs += ["-module-name", "TheName"] + freeCompilerArgs += listOf("-module-name", "TheName") } } } ``` -```kotlin + + + +```groovy kotlin { iosArm64("myapp") { binaries.framework { - freeCompilerArgs += listOf("-module-name", "TheName") + freeCompilerArgs += ["-module-name", "TheName"] } } } ``` + ## How do I rename the iOS framework? diff --git a/docs/topics/native/native-gradle.md b/docs/topics/native/native-gradle.md index 70047e597ec..643cee17554 100644 --- a/docs/topics/native/native-gradle.md +++ b/docs/topics/native/native-gradle.md @@ -23,11 +23,12 @@ Either can be used and samples will show the syntax for both languages. First, create a project directory. Inside it, create `build.gradle` or `build.gradle.kts` Gradle build file with the following contents: - + + -```groovy +```kotlin plugins { - id 'org.jetbrains.kotlin.multiplatform' version '%kotlinVersion%' + kotlin("multiplatform") version "%kotlinVersion%" } repositories { @@ -35,24 +36,27 @@ repositories { } kotlin { - macosX64('native') { // on macOS - // linuxX64('native') // on Linux - // mingwX64('native') // on Windows + macosX64("native") { // on macOS + // linuxX64("native") // on Linux + // mingwX64("native") // on Windows binaries { executable() } } } -wrapper { - gradleVersion = '%gradleVersion%' - distributionType = 'BIN' +tasks.withType { + gradleVersion = "%gradleVersion%" + distributionType = Wrapper.DistributionType.BIN } ``` -```kotlin + + + +```groovy plugins { - kotlin("multiplatform") version "%kotlinVersion%" + id 'org.jetbrains.kotlin.multiplatform' version '%kotlinVersion%' } repositories { @@ -60,21 +64,22 @@ repositories { } kotlin { - macosX64("native") { // on macOS - // linuxX64("native") // on Linux - // mingwX64("native") // on Windows + macosX64('native') { // on macOS + // linuxX64('native') // on Linux + // mingwX64('native') // on Windows binaries { executable() } } } -tasks.withType { - gradleVersion = "%gradleVersion%" - distributionType = Wrapper.DistributionType.BIN +wrapper { + gradleVersion = '%gradleVersion%' + distributionType = 'BIN' } ``` + Next, create an empty `settings.gradle` or `settings.gradle.kts` file in the project folder. diff --git a/docs/topics/native/native-ios-symbolication.md b/docs/topics/native/native-ios-symbolication.md index 68b15362ea1..2f109218f75 100644 --- a/docs/topics/native/native-ios-symbolication.md +++ b/docs/topics/native/native-ios-symbolication.md @@ -18,11 +18,12 @@ By default, Kotlin/Native compiler produces `.dSYM` for release compiler flag. At the same time, this option is disabled by default for other platforms. To enable it, use the `-Xadd-light-debug=enable` compiler option. - + + -```groovy +```kotlin kotlin { - targets.withType(org.jetbrains.kotlin.gradle.plugin.mpp.KotlinNativeTarget) { + targets.withType { binaries.all { freeCompilerArgs += "-Xadd-light-debug={enable|disable}" } @@ -30,10 +31,12 @@ kotlin { } ``` + + -```kotlin +```groovy kotlin { - targets.withType { + targets.withType(org.jetbrains.kotlin.gradle.plugin.mpp.KotlinNativeTarget) { binaries.all { freeCompilerArgs += "-Xadd-light-debug={enable|disable}" } @@ -41,6 +44,7 @@ kotlin { } ``` + In projects created from IntelliJ IDEA or AppCode templates these `.dSYM` bundles @@ -56,28 +60,33 @@ If rebuilding is performed on App Store side, then `.dSYM` of rebuilt *dynamic* seems discarded and not downloadable from App Store Connect. In this case, it may be required to make the framework static. - + + -```groovy +```kotlin kotlin { - targets.withType(org.jetbrains.kotlin.gradle.plugin.mpp.KotlinNativeTarget) { - binaries.withType(org.jetbrains.kotlin.gradle.plugin.mpp.Framework) { + targets.withType { + binaries.withType { isStatic = true } } } ``` -```kotlin + + + +```groovy kotlin { - targets.withType { - binaries.withType { + targets.withType(org.jetbrains.kotlin.gradle.plugin.mpp.KotlinNativeTarget) { + binaries.withType(org.jetbrains.kotlin.gradle.plugin.mpp.Framework) { isStatic = true } } } ``` + ## Decode inlined stack frames diff --git a/docs/topics/opt-in-requirements.md b/docs/topics/opt-in-requirements.md index 4b96f75d856..d9df98f7af5 100644 --- a/docs/topics/opt-in-requirements.md +++ b/docs/topics/opt-in-requirements.md @@ -145,7 +145,17 @@ Compiling with this argument has the same effect as if every declaration in the If you build your module with Gradle, you can add arguments like this: - + + + +```kotlin +tasks.withType().configureEach { + kotlinOptions.freeCompilerArgs += "-opt-in=org.mylibrary.OptInAnnotation" +} +``` + + + ```groovy tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).configureEach { @@ -155,36 +165,36 @@ tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).configureEach { } ``` -```kotlin -tasks.withType().configureEach { - kotlinOptions.freeCompilerArgs += "-opt-in=org.mylibrary.OptInAnnotation" -} -``` - + If your Gradle module is a multiplatform module, use the `optIn` method: - + + -```groovy +```kotlin sourceSets { all { - languageSettings { - optIn('org.mylibrary.OptInAnnotation') - } + languageSettings.optIn("org.mylibrary.OptInAnnotation") } } ``` -```kotlin + + + +```groovy sourceSets { all { - languageSettings.optIn("org.mylibrary.OptInAnnotation") + languageSettings { + optIn('org.mylibrary.OptInAnnotation') + } } } ``` + For Maven, it would be: diff --git a/docs/topics/ranges.md b/docs/topics/ranges.md index 71d7dac6831..b7c872350c5 100644 --- a/docs/topics/ranges.md +++ b/docs/topics/ranges.md @@ -5,7 +5,7 @@ function from the `kotlin.ranges` package and its operator form `..`. Usually, ` `!in` functions. ```kotlin -if (i in 1..4) { // equivalent of 1 <= i && i <= 4 +if (i in 1..4) { // equivalent of 1 <= i && i <= 4 print(i) } ``` diff --git a/docs/topics/reflection.md b/docs/topics/reflection.md index 0ce3ef334af..973dc43cfaf 100644 --- a/docs/topics/reflection.md +++ b/docs/topics/reflection.md @@ -17,20 +17,25 @@ library for applications that do not use reflection features. To use reflection in a Gradle or Maven project, add the dependency on `kotlin-reflect`: * In Gradle: - - - ```groovy + + + + ```kotlin dependencies { - implementation "org.jetbrains.kotlin:kotlin-reflect:%kotlinVersion%" + implementation("org.jetbrains.kotlin:kotlin-reflect:%kotlinVersion%") } ``` + + + - ```kotlin + ```groovy dependencies { - implementation("org.jetbrains.kotlin:kotlin-reflect:%kotlinVersion%") + implementation "org.jetbrains.kotlin:kotlin-reflect:%kotlinVersion%" } ``` - + + * In Maven: diff --git a/docs/topics/serialization.md b/docs/topics/serialization.md index 28bc8e664c4..06d8273300f 100644 --- a/docs/topics/serialization.md +++ b/docs/topics/serialization.md @@ -55,40 +55,50 @@ Before starting, you’ll need to configure your build script so that you can us 1. Apply the Kotlin serialization Gradle plugin `org.jetbrains.kotlin.plugin.serialization` (or `kotlin(“plugin.serialization”)` in the Kotlin Gradle DSL). - + + - ```groovy + ```kotlin plugins { - id 'org.jetbrains.kotlin.jvm' version '%kotlinVersion%' - id 'org.jetbrains.kotlin.plugin.serialization' version '%kotlinVersion%' + kotlin("jvm") version "%kotlinVersion%" + kotlin("plugin.serialization") version "%kotlinVersion%" } ``` - ```kotlin + + + + ```groovy plugins { - kotlin("jvm") version "%kotlinVersion%" - kotlin("plugin.serialization") version "%kotlinVersion%" + id 'org.jetbrains.kotlin.jvm' version '%kotlinVersion%' + id 'org.jetbrains.kotlin.plugin.serialization' version '%kotlinVersion%' } ``` + 2. Add the JSON serialization library dependency:`org.jetbrains.kotlinx:kotlinx-serialization-json:%serializationVersion%` - + + - ```groovy + ```kotlin dependencies { - implementation 'org.jetbrains.kotlinx:kotlinx-serialization-json:%serializationVersion%' + implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:%serializationVersion%") } ``` - ```kotlin + + + + ```groovy dependencies { - implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:%serializationVersion%") + implementation 'org.jetbrains.kotlinx:kotlinx-serialization-json:%serializationVersion%' } ``` + Now you're ready to use the serialization API in your code. The API is located in the the `kotlinx.serialization` package diff --git a/docs/topics/whatsnew14.md b/docs/topics/whatsnew14.md index 390b49304da..b6124b4e548 100644 --- a/docs/topics/whatsnew14.md +++ b/docs/topics/whatsnew14.md @@ -63,36 +63,41 @@ Explicit API mode analyzes only the production sources of a module. To compile your module in the explicit API mode, add the following lines to your Gradle build script: - + + -```groovy +```kotlin kotlin { // for strict mode explicitApi() // or - explicitApi = 'strict' + explicitApi = ExplicitApiMode.Strict // for warning mode explicitApiWarning() // or - explicitApi = 'warning' + explicitApi = ExplicitApiMode.Warning } ``` -```kotlin + + + +```groovy kotlin { // for strict mode explicitApi() // or - explicitApi = ExplicitApiMode.Strict + explicitApi = 'strict' // for warning mode explicitApiWarning() // or - explicitApi = ExplicitApiMode.Warning + explicitApi = 'warning' } ``` + When using the command-line compiler, switch to explicit API mode by adding the `-Xexplicit-api` compiler option @@ -852,47 +857,52 @@ by connecting the source sets with the `dependsOn` relation. ![Hierarchical structure](hierarchical-structure.png) - + + -```groovy -kotlin { +```kotlin +kotlin{ sourceSets { - desktopMain { + val desktopMain by creating { dependsOn(commonMain) } - linuxX64Main { + val linuxX64Main by getting { dependsOn(desktopMain) } - mingwX64Main { + val mingwX64Main by getting { dependsOn(desktopMain) } - macosX64Main { + val macosX64Main by getting { dependsOn(desktopMain) } } } - ``` -```kotlin -kotlin{ + + + +```groovy +kotlin { sourceSets { - val desktopMain by creating { + desktopMain { dependsOn(commonMain) } - val linuxX64Main by getting { + linuxX64Main { dependsOn(desktopMain) } - val mingwX64Main by getting { + mingwX64Main { dependsOn(desktopMain) } - val macosX64Main by getting { + macosX64Main { dependsOn(desktopMain) } } } + ``` + Thanks to the hierarchical project structure, libraries can also provide common APIs for a subset of targets. Learn more @@ -913,33 +923,37 @@ that you can use in the shared code. From now on, instead of specifying dependencies on different variants of the same library in shared and platform-specific source sets where it is used, you should specify a dependency only once in the shared source set. - + + -```groovy +```kotlin kotlin { sourceSets { - commonMain { + val commonMain by getting { dependencies { - implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:%coroutinesVersion%' + implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:%coroutinesVersion%") } } } } ``` -```kotlin + + + +```groovy kotlin { sourceSets { - val commonMain by getting { + commonMain { dependencies { - implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:%coroutinesVersion%") + implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:%coroutinesVersion%' } } } } - ``` + Don’t use kotlinx library artifact names with suffixes specifying the platform, such as `-common`, `-native`, or similar, diff --git a/docs/topics/whatsnew1430.md b/docs/topics/whatsnew1430.md index fd606e5500d..0c227ebb3fb 100644 --- a/docs/topics/whatsnew1430.md +++ b/docs/topics/whatsnew1430.md @@ -199,20 +199,25 @@ new backend and share your feedback in our [issue tracker](https://kotl.in/issue To enable the new JVM IR backend, add the following lines to the project’s configuration file: * In Gradle: - - - ```groovy - tasks.withType(org.jetbrains.kotlin.gradle.dsl.KotlinJvmCompile) { + + + + ```kotlin + tasks.withType(org.jetbrains.kotlin.gradle.dsl.KotlinJvmCompile::class) { kotlinOptions.useIR = true } ``` - ```kotlin - tasks.withType(org.jetbrains.kotlin.gradle.dsl.KotlinJvmCompile::class) { + + + + ```groovy + tasks.withType(org.jetbrains.kotlin.gradle.dsl.KotlinJvmCompile) { kotlinOptions.useIR = true } ``` - + + * In Maven: diff --git a/docs/topics/whatsnew15.md b/docs/topics/whatsnew15.md index e73ffd8c121..59498eab08c 100644 --- a/docs/topics/whatsnew15.md +++ b/docs/topics/whatsnew15.md @@ -127,13 +127,8 @@ If you need to use the old backend in Kotlin 1.5.0, you can add the following li * In Gradle: - - - ```groovy - tasks.withType(org.jetbrains.kotlin.gradle.dsl.KotlinJvmCompile) { - kotlinOptions.useOldBackend = true - } - ``` + + ```kotlin tasks.withType { @@ -141,6 +136,16 @@ If you need to use the old backend in Kotlin 1.5.0, you can add the following li } ``` + + + + ```groovy + tasks.withType(org.jetbrains.kotlin.gradle.dsl.KotlinJvmCompile) { + kotlinOptions.useOldBackend = true + } + ``` + + * In Maven: @@ -594,35 +599,40 @@ the dependency `kotlin-test` in the common source set. Gradle uses JUnit 4 by default. Therefore, the `kotlin("test")` dependency resolves to the variant for JUnit 4, namely `kotlin-test-junit`: - + + -```groovy +```kotlin kotlin { sourceSets { - commonTest { + val commonTest by getting { dependencies { - implementation kotlin("test") // This brings the dependency - // on JUnit 4 transitively + implementation(kotlin("test")) // This brings the dependency + // on JUnit 4 transitively } } } } ``` -```kotlin + + + +```groovy kotlin { sourceSets { - val commonTest by getting { + commonTest { dependencies { - implementation(kotlin("test")) // This brings the dependency - // on JUnit 4 transitively + implementation kotlin("test") // This brings the dependency + // on JUnit 4 transitively } } } } ``` - + + You can choose JUnit 5 or TestNG by calling [`useJUnitPlatform()`]( https://docs.gradle.org/current/javadoc/org/gradle/api/tasks/testing/Test.html#useJUnitPlatform) or [`useTestNG()`](https://docs.gradle.org/current/javadoc/org/gradle/api/tasks/testing/Test.html#useTestNG) in the test task: diff --git a/docs/topics/whatsnew1520.md b/docs/topics/whatsnew1520.md index 92382edb3f2..c42fbd19ba6 100644 --- a/docs/topics/whatsnew1520.md +++ b/docs/topics/whatsnew1520.md @@ -137,23 +137,29 @@ This also works well with Swift. To try out this ability to export KDoc comments to Objective-C headers, use the `-Xexport-kdoc` compiler option. Add the following lines to `build.gradle(.kts)` of the Gradle projects you want to export comments from: - + + -```groovy +```kotlin kotlin { - targets.withType(org.jetbrains.kotlin.gradle.plugin.mpp.KotlinNativeTarget) { + targets.withType { compilations.get("main").kotlinOptions.freeCompilerArgs += "-Xexport-kdoc" } } ``` -```kotlin + + + +```groovy kotlin { - targets.withType { + targets.withType(org.jetbrains.kotlin.gradle.plugin.mpp.KotlinNativeTarget) { compilations.get("main").kotlinOptions.freeCompilerArgs += "-Xexport-kdoc" } } ``` + + We’d be very grateful if you would share your feedback with us using this [YouTrack ticket](https://youtrack.jetbrains.com/issue/KT-38600). diff --git a/docs/topics/whatsnew1530.md b/docs/topics/whatsnew1530.md index 45655559f68..8a85e1fa693 100644 --- a/docs/topics/whatsnew1530.md +++ b/docs/topics/whatsnew1530.md @@ -65,7 +65,8 @@ fun main() { To enable this feature in Kotlin 1.5.30, use language version `1.6`. You can also change the warnings to errors by enabling [progressive mode](whatsnew13.md#progressive-mode). - + + ```kotlin kotlin { @@ -78,6 +79,9 @@ kotlin { } ``` + + + ```groovy kotlin { sourceSets.all { @@ -89,6 +93,7 @@ kotlin { } ``` + ### Suspending functions as supertypes @@ -108,7 +113,8 @@ class MyClass: suspend () -> Unit { Use the `-language-version 1.6` compiler option to enable the feature: - + + ```kotlin kotlin { @@ -120,6 +126,9 @@ kotlin { } ``` + + + ```groovy kotlin { sourceSets.all { @@ -130,6 +139,7 @@ kotlin { } ``` + The feature has the following restrictions: @@ -441,7 +451,8 @@ XCFrameworks is useful if you want to use your KMM framework for devices and sim To use XCFrameworks, update your `build.gradle(.kts)` script: - + + ```kotlin import org.jetbrains.kotlin.gradle.plugin.mpp.apple.XCFramework @@ -474,6 +485,9 @@ kotlin { } ``` + + + ```groovy import org.jetbrains.kotlin.gradle.plugin.mpp.apple.XCFrameworkConfig @@ -505,6 +519,7 @@ kotlin { } ``` + When you declare XCFrameworks, these new Gradle tasks will be registered: @@ -571,7 +586,8 @@ A Java toolchain: Use the following code to set a toolchain. Replace the placeholder `` with the JDK version you would like to use: - + + ```kotlin kotlin { @@ -581,6 +597,9 @@ kotlin { } ``` + + + ```groovy kotlin { jvmToolchain { @@ -589,16 +608,13 @@ kotlin { } ``` - - + Note that setting a toolchain via the `kotlin` extension will update the toolchain for Java compile tasks as well. You can set a toolchain via the `java` extension, and Kotlin compilation tasks will use it: - - ```kotlin java { toolchain { @@ -607,16 +623,6 @@ java { } ``` -```groovy -java { - toolchain { - languageVersion.set(JavaLanguageVersion.of()) // “8” - } -} -``` - - - For information about setting any JDK version for `KotlinCompile` tasks, look through the docs about [setting the JDK version with the Task DSL](gradle.md#setting-jdk-version-with-the-task-dsl). For Gradle versions from 6.1 to 6.6, [use the `UsesKotlinJavaToolchain` interface to set the JDK home](#ability-to-specify-jdk-home-with-useskotlinjavatoolchain-interface). @@ -625,30 +631,36 @@ For Gradle versions from 6.1 to 6.6, [use the `UsesKotlinJavaToolchain` interfac All Kotlin tasks that support setting the JDK via [`kotlinOptions`](gradle.md#compiler-options) now implement the `UsesKotlinJavaToolchain` interface. To set the JDK home, put a path to your JDK and replace the `` placeholder: - + + ```kotlin project.tasks .withType() .configureEach { it.kotlinJavaToolchain.jdk.use( - "/path/to/your/jdk", - JavaVersion. + "/path/to/local/jdk", + JavaVersion. ) } ``` + + + + ```groovy project.tasks .withType(UsesKotlinJavaToolchain.class) .configureEach { it.kotlinJavaToolchain.jdk.use( - '/path/to/your/jdk', - JavaVersion. + '/path/to/local/jdk', + JavaVersion. ) } ``` + Use the `UsesKotlinJavaToolchain` interface for Gradle versions from 6.1 to 6.6. Starting from Gradle 6.7, use the [Java toolchains](#support-for-java-toolchains) instead. @@ -679,7 +691,8 @@ In Kotlin 1.5.30, there’s a new logic for the Kotlin daemon’s JVM arguments. * You can specify arguments in the `kotlin` extension: - + + ```kotlin kotlin { @@ -687,17 +700,22 @@ In Kotlin 1.5.30, there’s a new logic for the Kotlin daemon’s JVM arguments. } ``` + + + ```groovy kotlin { kotlinDaemonJvmArgs = ["-Xmx486m", "-Xms256m", "-XX:+UseParallelGC"] } ``` - + + * You can specify arguments for a specific task: - + + ```kotlin tasks @@ -706,6 +724,9 @@ In Kotlin 1.5.30, there’s a new logic for the Kotlin daemon’s JVM arguments. (this as CompileUsingKotlinDaemon).kotlinDaemonJvmArguments.set(listOf("-Xmx486m", "-Xms256m", "-XX:+UseParallelGC")) } ``` + + + ```groovy tasks @@ -717,6 +738,7 @@ In Kotlin 1.5.30, there’s a new logic for the Kotlin daemon’s JVM arguments. } ``` + > In this case a new Kotlin daemon instance can start on task execution. Learn more about [the Kotlin daemon’s interactions with JVM arguments](gradle.md#setting-kotlin-daemon-s-jvm-arguments).