diff --git a/docs/topics/maven.md b/docs/topics/maven.md index c2853a685d2..0f1dd23ec65 100644 --- a/docs/topics/maven.md +++ b/docs/topics/maven.md @@ -56,7 +56,21 @@ specify the ID and URL of each repository in the `` element: ## Set dependencies -Kotlin has an extensive standard library that can be used in your applications. +To add a dependency on a library, include it in the `` element: + +```xml + + + org.jetbrains.kotlinx + kotlinx-serialization-json + %serializationVersion% + + +``` + +### Dependency on the standard library + +Kotlin has an extensive standard library that you can use in your applications. To use the standard library in your project, add the following dependency to your `pom.xml` file: ```xml @@ -64,6 +78,8 @@ To use the standard library in your project, add the following dependency to you org.jetbrains.kotlin kotlin-stdlib + ${kotlin.version} @@ -73,13 +89,56 @@ To use the standard library in your project, add the following dependency to you > * 1.8, use `kotlin-stdlib-jdk7` or `kotlin-stdlib-jdk8`, respectively. > * 1.2, use `kotlin-stdlib-jre7` or `kotlin-stdlib-jre8`, respectively. > -{style="note"} +{style="note"} + +### Dependencies on test libraries If your project uses [Kotlin reflection](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.reflect.full/index.html) -or testing facilities, you need to add the corresponding dependencies as well. -The artifact IDs are `kotlin-reflect` for the reflection library, and `kotlin-test` and `kotlin-test-junit` +or testing frameworks, add the relevant dependencies. +Use `kotlin-reflect` for the reflection library, and `kotlin-test` and `kotlin-test-junit` for the testing libraries. +For example: + +```xml + + + org.jetbrains.kotlin + kotlin-reflect + ${kotlin.version} + + +``` + +### Dependency on a kotlinx library + +Depending on the kotlinx library, you can either add the base artifact name or the name with a `-jvm` suffix. Refer to +the library's README file on [klibs.io](https://klibs.io/). + +For example, to add a dependency on `kotlinx.coroutines`: + +```xml + + + org.jetbrains.kotlinx + kotlinx-coroutines-core + %coroutinesVersion% + + +``` + +To add a dependency on `kotlinx-datetime`: + +```xml + + + org.jetbrains.kotlinx + kotlinx-datetime-jvm + %dateTimeVersion% + + +``` + ## Compile Kotlin-only source code To compile source code, specify the source directories in the `` tag: @@ -135,25 +194,43 @@ If you need to configure an execution, you need to specify its ID. You can find ## Compile Kotlin and Java sources -To compile projects that include Kotlin and Java source code, invoke the Kotlin compiler before the Java compiler. -In Maven terms it means that `kotlin-maven-plugin` should be run before `maven-compiler-plugin` using the following method, -making sure that the `kotlin` plugin comes before the `maven-compiler-plugin` in your `pom.xml` file: +To compile a project with both Kotlin and Java source files, make sure the Kotlin compiler runs before the Java compiler. +The Java compiler can't see Kotlin declarations until they are compiled into `.class` files. +If your Java code uses Kotlin classes, those classes must be compiled first to avoid `cannot find symbol` errors. + +Maven determines plugin execution order based on two main factors: + +* The order of plugin declarations in the `pom.xml` file. +* Built-in default executions, such as `default-compile` and `default-testCompile`, which always run before user-defined executions, + regardless of their position in the `pom.xml` file. + +To control the execution order: + +* Declare `kotlin-maven-plugin` before `maven-compiler-plugin`. +* Disable the Java compiler plugin's default executions. +* Add custom executions to control the compile phases explicitly. + +> You can use the special none phase in Maven to disable a default execution. +> +{style="note"} + +Here's an example configuration: ```xml + org.jetbrains.kotlin kotlin-maven-plugin ${kotlin.version} - true + true - compile + kotlin-compile + compile - compile + compile @@ -163,10 +240,10 @@ making sure that the `kotlin` plugin comes before the `maven-compiler-plugin` in - test-compile - - test-compile + kotlin-test-compile + test-compile + + test-compile @@ -177,21 +254,24 @@ making sure that the `kotlin` plugin comes before the `maven-compiler-plugin` in + + org.apache.maven.plugins maven-compiler-plugin - 3.5.1 + 3.8.1 - + default-compile none - default-testCompile none + + java-compile compile @@ -212,6 +292,16 @@ making sure that the `kotlin` plugin comes before the `maven-compiler-plugin` in ``` +This configuration ensures the following: + +* Kotlin code is compiled first. +* Java code is compiled after Kotlin and can reference Kotlin classes. +* Default Maven behavior doesn't override the plugin order. + +For more details on how Maven handles plugin executions, +see [Guide to default plugin execution IDs](https://maven.apache.org/guides/mini/guide-default-execution-ids.html) in +the official Maven documentation. + ## Enable incremental compilation To make your builds faster, you can enable incremental compilation by adding the `kotlin.compiler.incremental` property: diff --git a/docs/topics/releases.md b/docs/topics/releases.md index 8271f7ad1b8..98cbc6fb10e 100644 --- a/docs/topics/releases.md +++ b/docs/topics/releases.md @@ -101,7 +101,7 @@ Alternatively, you can change the version of the `kotlin-maven-plugin` in your ` ``` If you have projects created with earlier Kotlin versions, check if you also need to [update the version of any kotlinx -libraries](maven.md#set-dependencies). +libraries](maven.md#dependency-on-a-kotlinx-library). > To learn more about how to work with Maven in your project, see [Maven](maven.md). >