From fd0c85d85bb8539e4422c3c799315e9fc5366fb5 Mon Sep 17 00:00:00 2001 From: Sarah Haggarty Date: Wed, 25 Oct 2023 11:55:01 +0200 Subject: [PATCH] update: add mavenlocal() repo warning --- .../get-started-with-jvm-gradle-project.md | 2 +- .../topics/gradle/gradle-configure-project.md | 70 +++++++++++++++++-- docs/topics/maven.md | 21 +++++- docs/topics/whatsnew18.md | 2 +- 4 files changed, 88 insertions(+), 7 deletions(-) diff --git a/docs/topics/gradle/get-started-with-jvm-gradle-project.md b/docs/topics/gradle/get-started-with-jvm-gradle-project.md index c936eb97be4..c581d37e400 100644 --- a/docs/topics/gradle/get-started-with-jvm-gradle-project.md +++ b/docs/topics/gradle/get-started-with-jvm-gradle-project.md @@ -80,7 +80,7 @@ application { As you can see, there are a few Kotlin-specific artifacts added to the Gradle build file: -1. In the `plugins` block, there is the `kotlin("jvm")` artifact – the plugin defines the version of Kotlin to be used in the project. +1. In the `plugins{}` block, there is the `kotlin("jvm")` artifact – the plugin defines the version of Kotlin to be used in the project. 2. In the `dependencies` section, there is `testImplementation(kotlin("test"))`. Learn more about [setting dependencies on test libraries](gradle-configure-project.md#set-dependencies-on-test-libraries). diff --git a/docs/topics/gradle/gradle-configure-project.md b/docs/topics/gradle/gradle-configure-project.md index 78706407cef..da00eb1f108 100644 --- a/docs/topics/gradle/gradle-configure-project.md +++ b/docs/topics/gradle/gradle-configure-project.md @@ -11,7 +11,7 @@ and [configure the project's dependencies](#configure-dependencies) there. ## Apply the plugin -To apply the Kotlin Gradle plugin, use the [`plugins` block](https://docs.gradle.org/current/userguide/plugins.html#sec:plugins_block) +To apply the Kotlin Gradle plugin, use the [`plugins{}` block](https://docs.gradle.org/current/userguide/plugins.html#sec:plugins_block) from the Gradle plugins DSL: @@ -187,7 +187,7 @@ tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinJvmCompile.class).configu To avoid JVM target incompatibility, [configure a toolchain](#gradle-java-toolchains-support) or align JVM versions manually. -#### What can go wrong if not checking targets compatibility {initial-collapse-state="collapsed"} +#### What can go wrong if targets are incompatible {initial-collapse-state="collapsed"} There are two ways of manually setting JVM targets for Kotlin and Java source sets: * The implicit way via [setting up a Java toolchain](#gradle-java-toolchains-support). @@ -601,7 +601,7 @@ plugins { ### Kotlin and Java sources for JavaScript 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: +project contains Java files). If you don't store them separately, specify the source folder in the `sourceSets{}` block: @@ -665,7 +665,7 @@ project.plugins.withType(KotlinBasePlugin.class) { ## Configure dependencies 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. +`dependencies{}` block of the source sets DSL. @@ -1150,6 +1150,68 @@ dependencies { +## Declare repositories + +You can declare a publicly-available repository to use its open source dependencies. In the `repositories{}` block, set +the name of the repository: + + + + +```kotlin +repositories { + mavenCentral() +} +``` + + + +```kotlin +repositories { + mavenCentral() +} +``` + + + +Popular repositories are [Maven Central](https://central.sonatype.com/) and [Google's Maven repository](https://maven.google.com/web/index.html). + +> If you also work with Maven projects, we recommend avoiding adding `mavenLocal()` as a repository because you +> may experience problems when switching between Gradle and Maven projects. If you must add the `mavenLocal()` repository, +> add it as the last repository in your `repositories{}` block. For more information, see +> [The case for mavenLocal()](https://docs.gradle.org/current/userguide/declaring_repositories.html#sec:case-for-maven-local). +> +{type="warning"} + +If you need to declare the same repositories in more than one subproject, declare the repositories centrally in the +`dependencyResolutionManagement{}` block in your `settings.gradle(.kts)` file: + + + + +```kotlin +dependencyResolutionManagement { + repositories { + mavenCentral() + } +} +``` + + + +```kotlin +dependencyResolutionManagement { + repositories { + mavenCentral() + } +} +``` + + + +Any declared repositories in subprojects override repositories declared centrally. For more information on how to control +this behavior and what options are available, see [Gradle's documentation](https://docs.gradle.org/current/userguide/declaring_repositories.html#sub:centralized-repository-declaration). + ## What's next? Learn more about: diff --git a/docs/topics/maven.md b/docs/topics/maven.md index 5b9c4b196e3..cf872f1d8e0 100644 --- a/docs/topics/maven.md +++ b/docs/topics/maven.md @@ -6,7 +6,7 @@ Maven is a build system that you can use to build and manage any Java-based proj The *kotlin-maven-plugin* compiles Kotlin sources and modules. Currently, only Maven v3 is supported. -Define the version of Kotlin you want to use via the `kotlin.version` property: +In your `pom.xml` file, define the version of Kotlin you want to use in the `kotlin.version` property: ```xml @@ -23,6 +23,25 @@ To use JDK 17, in your `.mvn/jvm.config` file, add: --add-opens=java.base/java.io=ALL-UNNAMED ``` +## Declare repositories + +By default, the `mavenCentral` repository is available for all Maven projects. To access artifacts in other repositories, +specify the ID and URL of each repository in the `` element: + +```xml + + + spring-repo + https://repo.spring.io/release + + +``` + +> If you declare `mavenLocal()` as a repository in a Gradle project, you may experience problems when switching +> between Gradle and Maven projects. For more information, see [Declare repositories](gradle-configure-project.md#declare-repositories). +> +{type="note"} + ## Set dependencies Kotlin has an extensive standard library that can be used in your applications. diff --git a/docs/topics/whatsnew18.md b/docs/topics/whatsnew18.md index bf83fbd8446..dbb4d90253c 100644 --- a/docs/topics/whatsnew18.md +++ b/docs/topics/whatsnew18.md @@ -535,7 +535,7 @@ The shift of the default value from `warning` to `error` is a preparation step f **We encourage you to set this property to `error`** and [configure a toolchain](gradle-configure-project.md#gradle-java-toolchains-support) or align JVM versions manually. -Learn more about [what can go wrong if you don't check the targets' compatibility](gradle-configure-project.md#what-can-go-wrong-if-not-checking-targets-compatibility). +Learn more about [what can go wrong if you don't check the targets' compatibility](gradle-configure-project.md#what-can-go-wrong-if-targets-are-incompatible). ### Resolution of Kotlin Gradle plugins' transitive dependencies