Gradleプロジェクトを構成する

Gradle を使用してKotlinプロジェクトをビルドするには、ビルドスクリプトファイル build.gradle(.kts) にKotlin Gradleプラグインを追加し、そこでプロジェクトの依存関係を構成する必要があります。

ビルドスクリプトの内容についてさらに学ぶには、 「ビルドスクリプトを探索する」セクションを参照してください。

プラグインを適用する

Kotlin Gradleプラグインを適用するには、GradleプラグインDSLの plugins{} ブロックを使用します。

KotlinGroovy

plugins {
    // `<...>` をターゲット環境に適したプラグイン名に置き換えてください
    kotlin("<...>") version "2.2.21"
    // 例えば、ターゲット環境がJVMの場合：
    // kotlin("jvm") version "2.2.21"
}

plugins {
    // `<...>` をターゲット環境に適したプラグイン名に置き換えてください
    id 'org.jetbrains.kotlin.<...>' version '2.2.21'
    // 例えば、ターゲット環境がJVMの場合： 
    // id 'org.jetbrains.kotlin.jvm' version '2.2.21'
}

Kotlin Gradleプラグイン (KGP) とKotlinは同じバージョン番号を共有します。

プロジェクトを構成する際、Kotlin Gradleプラグイン (KGP) と利用可能なGradleバージョンの互換性を確認してください。以下の表に、GradleおよびAndroid Gradleプラグイン (AGP) の最小および最大完全にサポートされているバージョンを示します。

KGPバージョン	Gradleの最小および最大バージョン	AGPの最小および最大バージョン
2.2.20	7.6.3–8.14	7.3.1–8.11.1
2.2.0-2.2.10	7.6.3-8.14	7.3.1-8.10.0
2.1.20-2.1.21	7.6.3–8.12.1	7.3.1–8.7.2
2.1.0–2.1.10	7.6.3–8.10*	7.3.1–8.7.2
2.0.20–2.0.21	6.8.3–8.8*	7.1.3–8.5
2.0.0	6.8.3–8.5	7.1.3–8.3.1
1.9.20–1.9.25	6.8.3–8.1.1	4.2.2–8.1.0
1.9.0–1.9.10	6.8.3–7.6.0	4.2.2–7.4.0
1.8.20–1.8.22	6.8.3–7.6.0	4.1.3–7.4.0
1.8.0–1.8.11	6.8.3–7.3.3	4.1.3–7.2.1
1.7.20–1.7.22	6.7.1–7.1.1	3.6.4–7.0.4
1.7.0–1.7.10	6.7.1–7.0.2	3.4.3–7.0.2
1.6.20–1.6.21	6.1.1–7.0.2	3.4.3–7.0.2

*Kotlin 2.0.20–2.0.21およびKotlin 2.1.0–2.1.10は、Gradle 8.6まで完全に互換性があります。 Gradleバージョン8.7–8.10もサポートされていますが、1つだけ例外があります。Kotlin Multiplatform Gradleプラグインを使用している場合、 JVMターゲットでwithJava()関数を呼び出すマルチプラットフォームプロジェクトで非推奨の警告が表示されることがあります。 詳細については、デフォルトで作成されるJavaソースセットを参照してください。

GradleおよびAGPバージョンは最新リリースまで使用できますが、その場合、非推奨の警告に遭遇したり、一部の新機能が動作しない可能性があることに留意してください。

例えば、Kotlin Gradleプラグインおよびkotlin-multiplatformプラグイン 2.2.21 は、プロジェクトをコンパイルするために最低限のGradleバージョンとして 7.6.3 を必要とします。

同様に、最大の完全にサポートされているバージョンは 8.14 です。これは非推奨のGradleメソッドやプロパティを持たず、現在のすべてのGradle機能をサポートしています。

プロジェクト内のKotlin Gradleプラグインデータ

デフォルトでは、Kotlin Gradleプラグインは永続的なプロジェクト固有のデータをプロジェクトのルートにある.kotlinディレクトリに保存します。

.kotlinディレクトリをバージョン管理にコミットしないでください。 例えば、Gitを使用している場合、プロジェクトの.gitignoreファイルに.kotlinを追加してください。

この動作を構成するために、プロジェクトのgradle.propertiesファイルに追加できるプロパティがあります。

Gradleプロパティ	説明
kotlin.project.persistent.dir	プロジェクトレベルのデータが保存される場所を構成します。デフォルト: <project-root-directory>/.kotlin
kotlin.project.persistent.dir.gradle.disableWrite	.gradleディレクトリへのKotlinデータの書き込みを無効にするかどうかを制御します（古いIDEAバージョンとの下位互換性のため）。デフォルト: false

JVMをターゲットにする

JVMをターゲットにするには、Kotlin JVMプラグインを適用します。

KotlinGroovy

plugins {
    kotlin("jvm") version "2.2.21"
}

plugins {
    id "org.jetbrains.kotlin.jvm" version "2.2.21"
}

このブロックのversionはリテラルであるべきであり、他のビルドスクリプトから適用することはできません。

KotlinとJavaのソース

KotlinソースとJavaソースは同じディレクトリに保存することも、異なるディレクトリに配置することもできます。

デフォルトの規約では、異なるディレクトリを使用します。

project
    - src
        - main (root)
            - kotlin
            - java

src/*/kotlinディレクトリにJavaの.javaファイルを保存しないでください。.javaファイルはコンパイルされません。

代わりに、src/main/javaを使用できます。

デフォルトの規約を使用しない場合、対応するsourceSetsプロパティを更新する必要があります。

KotlinGroovy

sourceSets.main {
    java.srcDirs("src/main/myJava", "src/main/myKotlin")
}

sourceSets {
    main.kotlin.srcDirs += 'src/main/myKotlin'
    main.java.srcDirs += 'src/main/myJava'
}

関連するコンパイルタスクのJVMターゲット互換性の確認

ビルドモジュールには、関連するコンパイルタスクがある場合があります。例えば、次のとおりです。

• compileKotlin と compileJava
• compileTestKotlin と compileTestJava

mainとtestソースセットのコンパイルタスクは関連していません。

このような関連するタスクの場合、Kotlin GradleプラグインはJVMターゲットの互換性をチェックします。kotlin拡張またはタスクの jvmTarget属性と、java拡張またはタスクの targetCompatibilityの値が異なる場合、JVMターゲットの非互換性が発生します。例えば、compileKotlinタスクにjvmTarget=1.8があり、compileJavaタスクに（または継承している）targetCompatibility=15がある場合などです。

このチェックの動作をプロジェクト全体に対して構成するには、gradle.propertiesファイルでkotlin.jvm.target.validation.modeプロパティを次のように設定します。

• error – プラグインがビルドを失敗させます。Gradle 8.0+のプロジェクトのデフォルト値です。
• warning – プラグインが警告メッセージを出力します。Gradle 8.0未満のプロジェクトのデフォルト値です。
• ignore – プラグインがチェックをスキップし、メッセージを出力しません。

build.gradle(.kts)ファイルでタスクレベルで構成することもできます。

KotlinGroovy

tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinJvmCompile>().configureEach {
    jvmTargetValidationMode.set(org.jetbrains.kotlin.gradle.dsl.jvm.JvmTargetValidationMode.WARNING)
}

tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinJvmCompile.class).configureEach {
    jvmTargetValidationMode = org.jetbrains.kotlin.gradle.dsl.jvm.JvmTargetValidationMode.WARNING
}

JVMターゲットの非互換性を避けるには、ツールチェーンを構成するか、JVMバージョンを手動で調整します。

ターゲットに互換性がない場合に発生しうる問題

KotlinおよびJavaソースセットのJVMターゲットを手動で設定する方法は2つあります。

• Javaツールチェーンを設定することによる暗黙的な方法。
• kotlin拡張またはタスクでjvmTarget属性を、java拡張またはタスクでtargetCompatibilityを明示的に設定することによる方法。

JVMターゲットの非互換性は、次の場合に発生します。

• jvmTargetとtargetCompatibilityに異なる値を明示的に設定した場合。
• デフォルト設定で、JDKが1.8と等しくない場合。

ビルドスクリプトにKotlin JVMプラグインのみがあり、JVMターゲットに対する追加設定がない場合のJVMターゲットのデフォルト設定を考えてみましょう。

KotlinGroovy

plugins {
    kotlin("jvm") version "2.2.21"
}

plugins {
    id "org.jetbrains.kotlin.jvm" version "2.2.21"
}

ビルドスクリプトにjvmTarget値に関する明示的な情報がない場合、そのデフォルト値はnullであり、コンパイラはそれをデフォルト値1.8に変換します。targetCompatibilityは現在のGradleのJDKバージョンと等しく、これはあなたのJDKバージョンと等しくなります（Javaツールチェーンアプローチを使用しない限り）。あなたのJDKバージョンが17であると仮定すると、公開されたライブラリアーティファクトはJDK 17+との互換性を宣言します: org.gradle.jvm.version=17。これは間違っています。この場合、バイトコードのバージョンが1.8であるにもかかわらず、このライブラリを追加するためにメインプロジェクトでJava 17を使用する必要があります。この問題を解決するには、ツールチェーンを構成してください。

Gradle Javaツールチェーンのサポート

Androidユーザーへの警告。Gradleツールチェーンのサポートを使用するには、Android Gradleプラグイン (AGP) バージョン8.1.0-alpha09以降を使用してください。

Gradle Javaツールチェーンのサポートは、AGP 7.4.0以降で利用可能です。 それにもかかわらず、この問題のため、AGPはバージョン8.1.0-alpha09までtargetCompatibilityをツールチェーンのJDKと等しく設定しませんでした。 8.1.0-alpha09未満のバージョンを使用する場合、compileOptionsを介してtargetCompatibilityを手動で構成する必要があります。 プレースホルダー<MAJOR_JDK_VERSION>を使用したいJDKバージョンに置き換えてください。

android {
    compileOptions {
        sourceCompatibility = <MAJOR_JDK_VERSION>
        targetCompatibility = <MAJOR_JDK_VERSION>
    }
}

Gradle 6.7では、Javaツールチェーンのサポートが導入されました。この機能を使用すると、次のことができます。

• コンパイル、テスト、および実行可能ファイルを実行するために、Gradle内のものとは異なるJDKとJREを使用する。
• まだリリースされていない言語バージョンでコードをコンパイルおよびテストする。

ツールチェーンのサポートにより、GradleはローカルJDKを自動検出し、ビルドのためにGradleが必要とする不足しているJDKをインストールできます。これでGradle自体はどのJDK上でも実行でき、主要なJDKバージョンに依存するタスクのリモートビルドキャッシュ機能を再利用できます。

Kotlin Gradleプラグインは、Kotlin/JVMコンパイルタスクに対してJavaツールチェーンをサポートします。JSおよびNativeタスクはツールチェーンを使用しません。Kotlinコンパイラは常にGradleデーモンが実行されているJDK上で実行されます。 Javaツールチェーンは次のことを行います。

• JVMターゲットで利用可能な-jdk-homeオプションを設定します。
• ユーザーがjvmTargetオプションを明示的に設定しない場合、compilerOptions.jvmTargetをツールチェーンのJDKバージョンに設定します。ユーザーがツールチェーンを構成しない場合、jvmTargetフィールドはデフォルト値を使用します。JVMターゲットの互換性についてさらに学ぶ。
• Javaのコンパイル、テスト、およびjavadocタスクによって使用されるツールチェーンを設定します。
• kaptワーカーがどのJDKで実行されるかに影響します。

ツールチェーンを設定するには、以下のコードを使用します。プレースホルダー<MAJOR_JDK_VERSION>を使用したいJDKバージョンに置き換えてください。

KotlinGroovy

kotlin {
    jvmToolchain {
        languageVersion.set(JavaLanguageVersion.of(<MAJOR_JDK_VERSION>))
    }
    // Or shorter:
    jvmToolchain(<MAJOR_JDK_VERSION>)
    // For example:
    jvmToolchain(17)
}

kotlin {
    jvmToolchain {
        languageVersion = JavaLanguageVersion.of(<MAJOR_JDK_VERSION>)
    }
    // Or shorter:
    jvmToolchain(<MAJOR_JDK_VERSION>)
    // For example:
    jvmToolchain(17)
}

kotlin拡張を介してツールチェーンを設定すると、Javaコンパイルタスクのツールチェーンも更新されることに注意してください。

java拡張を介してツールチェーンを設定でき、Kotlinコンパイルタスクはそれを使用します。

KotlinGroovy

java {
    toolchain {
        languageVersion.set(JavaLanguageVersion.of(<MAJOR_JDK_VERSION>)) 
    }
}

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(<MAJOR_JDK_VERSION>)
    }
}

Gradle 8.0.2以降を使用している場合は、ツールチェーンリゾルバープラグインも追加する必要があります。この種のプラグインは、ツールチェーンをダウンロードするリポジトリを管理します。例として、settings.gradle(.kts)に以下のプラグインを追加してください。

KotlinGroovy

plugins {
    id("org.gradle.toolchains.foojay-resolver-convention") version("0.9.0")
}

plugins {
    id 'org.gradle.toolchains.foojay-resolver-convention' version '0.9.0'
}

foojay-resolver-conventionのバージョンがGradleサイトのGradleバージョンに対応していることを確認してください。

Gradleがどのツールチェーンを使用しているかを理解するには、ログレベル --infoでGradleビルドを実行し、出力で[KOTLIN] Kotlin compilation 'jdkHome' argument:で始まる文字列を見つけてください。 コロンの後の部分が、ツールチェーンからのJDKバージョンになります。

特定のタスクに任意のJDK（ローカルなものも含む）を設定するには、Task DSLを使用します。

KotlinプラグインでのGradle JVMツールチェーンのサポートについてさらに学ぶ。

Task DSLでJDKバージョンを設定する

Task DSLを使用すると、UsesKotlinJavaToolchainインターフェースを実装する任意のタスクに対して、任意のJDKバージョンを設定できます。現在、これらのタスクはKotlinCompileとKaptTaskです。Gradleに主要なJDKバージョンを検索させたい場合は、ビルドスクリプトの<MAJOR_JDK_VERSION>プレースホルダーを置き換えてください。

KotlinGroovy

val service = project.extensions.getByType<JavaToolchainService>()
val customLauncher = service.launcherFor {
    languageVersion.set(JavaLanguageVersion.of(<MAJOR_JDK_VERSION>))
}
project.tasks.withType<UsesKotlinJavaToolchain>().configureEach {
    kotlinJavaToolchain.toolchain.use(customLauncher)
}

JavaToolchainService service = project.getExtensions().getByType(JavaToolchainService.class)
Provider<JavaLauncher> customLauncher = service.launcherFor {
    it.languageVersion = JavaLanguageVersion.of(<MAJOR_JDK_VERSION>)
}
tasks.withType(UsesKotlinJavaToolchain::class).configureEach { task ->
    task.kotlinJavaToolchain.toolchain.use(customLauncher)
}

または、ローカルJDKへのパスを指定し、プレースホルダー<LOCAL_JDK_VERSION>をこのJDKバージョンに置き換えることができます。

tasks.withType<UsesKotlinJavaToolchain>().configureEach {
    kotlinJavaToolchain.jdk.use(
        "/path/to/local/jdk", // お使いのJDKへのパスを指定してください
        JavaVersion.<LOCAL_JDK_VERSION> // 例えば、JavaVersion.17
    )
}

コンパイラタスクを関連付ける

コンパイルを_関連付け_ることで、あるコンパイルが別のコンパイルのコンパイル済み出力を使用するような関係をそれらの間に設定できます。コンパイルを関連付けることで、それらの間にinternalの可視性が確立されます。

Kotlinコンパイラは、デフォルトで一部のコンパイルを関連付けます。例えば、各ターゲットのtestとmainコンパイルなどです。カスタムコンパイルの1つが別のコンパイルと接続されていることを表現する必要がある場合は、独自の関連付けられたコンパイルを作成します。

IDEがソースセット間の可視性を推論するために、関連するコンパイルをサポートするようにするには、build.gradle(.kts)に以下のコードを追加してください。

KotlinGroovy

val integrationTestCompilation = kotlin.target.compilations.create("integrationTest") {
    associateWith(kotlin.target.compilations.getByName("main"))
}

integrationTestCompilation {
    kotlin.target.compilations.create("integrationTest") {
        associateWith(kotlin.target.compilations.getByName("main"))
    }
}

ここでは、integrationTestコンパイルがmainコンパイルと関連付けられており、関数テストからのinternalオブジェクトへのアクセスを提供します。

Java Modules (JPMS) を有効にして構成する

Kotlin GradleプラグインがJava Modulesで動作するようにするには、ビルドスクリプトに以下の行を追加し、YOUR_MODULE_NAMEをJPMSモジュールへの参照（例: org.company.module）に置き換えてください。

KotlinGroovy

// Gradleのバージョンが7.0未満の場合は、以下の3行を追加してください
java {
    modularity.inferModulePath.set(true)
}

tasks.named("compileJava", JavaCompile::class.java) {
    options.compilerArgumentProviders.add(CommandLineArgumentProvider {
        // コンパイルされたKotlinクラスをjavacに提供します – Java/Kotlin混合ソースが機能するために必要です
        listOf("--patch-module", "YOUR_MODULE_NAME=${sourceSets["main"].output.asPath}")
    })
}

// Gradleのバージョンが7.0未満の場合は、以下の3行を追加してください
java {
    modularity.inferModulePath = true
}

tasks.named("compileJava", JavaCompile.class) {
    options.compilerArgumentProviders.add(new CommandLineArgumentProvider() {
        @Override
        Iterable<String> asArguments() {
            // コンパイルされたKotlinクラスをjavacに提供します – Java/Kotlin混合ソースが機能するために必要です
            return ["--patch-module", "YOUR_MODULE_NAME=${sourceSets["main"].output.asPath}"]
        }
    })
}

module-info.javaは通常通りsrc/main/javaディレクトリに配置してください。

モジュールの場合、「package is empty or does not exist」というビルド失敗を避けるため、Kotlinファイルのパッケージ名はmodule-info.javaからのパッケージ名と等しくなければなりません。

詳細については、以下を参照してください。

• Javaモジュールシステム用のモジュールのビルド
• Javaモジュールシステムを使用したアプリケーションのビルド
• Kotlinにおける「モジュール」の意味

その他の詳細

Kotlin/JVMについてさらに学ぶ。

コンパイルタスクでの成果物の使用を無効にする

まれなシナリオでは、循環依存関係エラーによってビルド失敗が発生する可能性があります。例えば、複数のコンパイルがあり、あるコンパイルが別のコンパイルのすべての内部宣言を見ることができ、生成された成果物が両方のコンパイルタスクの出力に依存している場合などです。

FAILURE: Build failed with an exception.

What went wrong:
Circular dependency between the following tasks:
:lib:compileKotlinJvm
--- :lib:jvmJar
     \--- :lib:compileKotlinJvm (*)
(*) - details omitted (listed previously)

この循環依存関係エラーを修正するために、Gradleプロパティ archivesTaskOutputAsFriendModule を追加しました。このプロパティは、コンパイルタスクでの成果物入力の使用を制御し、結果としてタスク依存関係が作成されるかどうかを決定します。

デフォルトでは、このプロパティはタスク依存関係を追跡するためにtrueに設定されています。循環依存関係エラーに遭遇した場合、コンパイルタスクでの成果物の使用を無効にしてタスク依存関係を削除し、循環依存関係エラーを回避することができます。

コンパイルタスクでの成果物の使用を無効にするには、gradle.propertiesファイルに以下を追加してください。

kotlin.build.archivesTaskOutputAsFriendModule=false

遅延Kotlin/JVMタスク作成

Kotlin 1.8.20以降、Kotlin Gradleプラグインはすべてのタスクを登録し、ドライランではそれらを構成しません。

コンパイルタスクのdestinationDirectoryの非デフォルトロケーション

Kotlin/JVM KotlinJvmCompile/KotlinCompileタスクのdestinationDirectoryロケーションをオーバーライドする場合、ビルドスクリプトを更新してください。JARファイル内のsourceSets.main.outputsにsourceSets.main.kotlin.classesDirectoriesを明示的に追加する必要があります。

tasks.jar(type: Jar) {
    from sourceSets.main.outputs
    from sourceSets.main.kotlin.classesDirectories
}

複数プラットフォームをターゲットにする

複数プラットフォームをターゲットとするプロジェクトは、マルチプラットフォームプロジェクトと呼ばれ、kotlin-multiplatformプラグインを必要とします。

kotlin-multiplatformプラグインは、Gradle 7.6.3以降で動作します。

KotlinGroovy

plugins {
    kotlin("multiplatform") version "2.2.21"
}

plugins {
    id 'org.jetbrains.kotlin.multiplatform' version '2.2.21'
}

異なるプラットフォーム向けKotlin MultiplatformおよびiOSとAndroid向けKotlin Multiplatformについてさらに学ぶ。

Androidをターゲットにする

Androidアプリケーションを作成するには、Android Studioを使用することをお勧めします。Android Gradleプラグインの使用方法を学ぶ。

Webをターゲットにする

Kotlinは、Kotlin Multiplatformを介して、Web開発のための2つのアプローチを提供します。

• JavaScriptベース (Kotlin/JSコンパイラを使用)
• WebAssemblyベース (Kotlin/Wasmコンパイラを使用)

どちらのアプローチもKotlin Multiplatformプラグインを使用しますが、異なるユースケースをサポートします。以下のセクションでは、Gradleビルドで各ターゲットを構成する方法と、それらを使用するタイミングについて説明します。

JavaScriptをターゲットにする

目標が次のいずれかである場合は、Kotlin/JSを使用してください。

• ビジネスロジックをJavaScript/TypeScriptコードベースと共有する
• 共有できないWebアプリをKotlinで構築する

詳細については、Kotlin Multiplatformプロジェクトに適したWebターゲットを選択するを参照してください。

JavaScriptをターゲットにする場合、kotlin-multiplatformプラグインを使用します。

KotlinGroovy

plugins {
    kotlin("multiplatform") version "2.2.21"
}

plugins {
    id 'org.jetbrains.kotlin.multiplatform' version '2.2.21'
}

JavaScriptターゲットを構成するには、ブラウザまたはNode.js環境のどちらで実行するかを指定します。

kotlin {
    js().browser {  // or js().nodejs
        /* ... */
    }
}

JavaScriptのGradle構成に関する詳細とKotlin/JSプロジェクトのセットアップについてさらに学ぶ。

WebAssemblyをターゲットにする

複数のプラットフォーム間でロジックとUIの両方を共有したい場合は、Kotlin/Wasmを使用してください。詳細については、Kotlin Multiplatformプロジェクトに適したWebターゲットを選択するを参照してください。

JavaScriptと同様に、WebAssembly (Wasm) をターゲットにする場合、kotlin-multiplatformプラグインを使用します。

KotlinGroovy

plugins {
    kotlin("multiplatform") version "2.2.21"
}

plugins {
    id 'org.jetbrains.kotlin.multiplatform' version '2.2.21'
}

要件に応じて、以下をターゲットにできます。

• wasmJs: ブラウザまたはNode.jsでの実行用
• wasmWasi: Wasmtime、WasmEdgeなどのWASI (WebAssembly System Interface)をサポートするWasm環境での実行用。

wasmJsターゲットをWebブラウザまたはNode.js用に構成します。

kotlin {
    wasmJs {
        browser { // or nodejs
            /* ... */
        }
    }
}

WASI環境の場合、wasmWasiターゲットを構成します。

kotlin {
    wasmWasi {
        nodejs {
            /* ... */
        }
    }
}

WasmのGradle構成に関する詳細を参照してください。

Webターゲット向けのKotlinおよびJavaソース

KGPはKotlinファイルのみで動作するため、KotlinファイルとJavaファイルは分けておくことをお勧めします（プロジェクトにJavaファイルが含まれている場合）。別々に保存しない場合は、sourceSets{}ブロックでソースフォルダを指定してください。

KotlinGroovy

kotlin {
    sourceSets["main"].apply {
        kotlin.srcDir("src/main/myKotlin")
    }
}

kotlin {
    sourceSets {
        main.kotlin.srcDirs += 'src/main/myKotlin'
    }
}

KotlinBasePluginインターフェースによる構成アクションのトリガー

任意のKotlin Gradleプラグイン（JVM、JS、マルチプラットフォーム、Nativeなど）が適用されるたびに、いくつかの構成アクションをトリガーするには、すべてのKotlinプラグインが継承するKotlinBasePluginインターフェースを使用します。

KotlinGroovy

import org.jetbrains.kotlin.gradle.plugin.KotlinBasePlugin

// ...

project.plugins.withType<KotlinBasePlugin>() {
    // ここでアクションを構成します
}

import org.jetbrains.kotlin.gradle.plugin.KotlinBasePlugin

// ...

project.plugins.withType(KotlinBasePlugin.class) {
    // ここでアクションを構成します
}

依存関係を構成する

ライブラリに依存関係を追加するには、ソースセットDSLのdependencies{}ブロックで、必要なタイプの依存関係（例: implementation）を設定します。

KotlinGroovy

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("com.example:my-library:1.0")
        }
    }
}

kotlin {
    sourceSets {
        commonMain {
            dependencies {
                implementation 'com.example:my-library:1.0'
            }
        }
    }
}

Experimental

トップレベルで依存関係を構成する

マルチプラットフォームプロジェクトでは、トップレベルのdependencies {}ブロックを使用して共通の依存関係を構成できます。ここで宣言された依存関係は、commonMainまたはcommonTestソースセットに追加されたかのように動作します。

トップレベルのdependencies {}ブロックを使用するには、ブロックの前に@OptIn(ExperimentalKotlinGradlePluginApi::class)アノテーションを追加してオプトインしてください。

KotlinGroovy

kotlin {
    @OptIn(ExperimentalKotlinGradlePluginApi::class)
    dependencies {
        implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.2")
    }
}

kotlin {
    dependencies {
        implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.2'
    }
}

対応するターゲットのsourceSets {}ブロック内にプラットフォーム固有の依存関係を追加してください。

この機能に関するフィードバックは、YouTrackで共有できます。

依存関係のタイプ

要件に基づいて依存関係のタイプを選択してください。

タイプ	説明	使用すべき場合
api	コンパイル時と実行時の両方で使用され、ライブラリのコンシューマーにエクスポートされます。	依存関係からの型が現在のモジュールの公開APIで使用される場合、api依存関係を使用します。
implementation	現在のモジュールのコンパイル時と実行時に使用されますが、implementation依存関係を持つモジュールに依存する他のモジュールのコンパイルには公開されません。	モジュールの内部ロジックに必要な依存関係に使用します。 モジュールが公開されないエンドポイントアプリケーションである場合、api依存関係の代わりにimplementation依存関係を使用します。
compileOnly	現在のモジュールのコンパイルに使用され、実行時にも他のモジュールのコンパイル時にも利用できません。	実行時にサードパーティの実装が利用可能なAPIに使用します。
runtimeOnly	実行時には利用可能ですが、どのモジュールのコンパイル時にも可視ではありません。

標準ライブラリへの依存関係

標準ライブラリ（stdlib）への依存関係は、各ソースセットに自動的に追加されます。使用される標準ライブラリのバージョンは、Kotlin Gradleプラグインのバージョンと同じです。

プラットフォーム固有のソースセットの場合、対応するプラットフォーム固有のライブラリのバリアントが使用され、残りのソースセットには共通の標準ライブラリが追加されます。Kotlin Gradleプラグインは、GradleビルドスクリプトのcompilerOptions.jvmTargetコンパイラオプションに応じて適切なJVM標準ライブラリを選択します。

標準ライブラリの依存関係を明示的に宣言する場合（例えば、異なるバージョンが必要な場合）、Kotlin Gradleプラグインはそれをオーバーライドしたり、2つ目の標準ライブラリを追加したりすることはありません。

標準ライブラリがまったく必要ない場合は、gradle.propertiesファイルに以下のGradleプロパティを追加できます。

kotlin.stdlib.default.dependency=false

遷移的な依存関係のバージョン調整

Kotlin標準ライブラリバージョン1.9.20以降、Gradleは標準ライブラリに含まれるメタデータを使用して、遷移的なkotlin-stdlib-jdk7およびkotlin-stdlib-jdk8の依存関係を自動的に調整します。

1.8.0～1.9.10のいずれかのKotlin標準ライブラリバージョンに対して依存関係を追加した場合（例: implementation("org.jetbrains.kotlin:kotlin-stdlib:1.8.0")）、Kotlin Gradleプラグインは遷移的なkotlin-stdlib-jdk7およびkotlin-stdlib-jdk8の依存関係にこのKotlinバージョンを使用します。これにより、異なる標準ライブラリバージョンからのクラス重複が回避されます。kotlin-stdlib-jdk7とkotlin-stdlib-jdk8をkotlin-stdlibにマージすることについてさらに学ぶ。この動作を無効にするには、gradle.propertiesファイルでkotlin.stdlib.jdk.variants.version.alignment Gradleプロパティを使用します。

kotlin.stdlib.jdk.variants.version.alignment=false

その他のバージョン調整方法

• バージョン調整に問題がある場合、Kotlin BOMを介してすべてのバージョンを調整できます。ビルドスクリプトでkotlin-bomへのプラットフォーム依存関係を宣言してください。

  KotlinGroovy

  implementation(platform("org.jetbrains.kotlin:kotlin-bom:2.2.21"))

  implementation platform('org.jetbrains.kotlin:kotlin-bom:2.2.21')

• 標準ライブラリバージョンに対する依存関係を追加しない場合でも、Kotlin標準ライブラリの異なる古いバージョンを遷移的に引き起こす2つの異なる依存関係がある場合は、これらの遷移的なライブラリの2.2.21バージョンを明示的に要求できます。

  KotlinGroovy

  dependencies {
      constraints {
          add("implementation", "org.jetbrains.kotlin:kotlin-stdlib-jdk7") {
              version {
                  require("2.2.21")
              }
          }
          add("implementation", "org.jetbrains.kotlin:kotlin-stdlib-jdk8") {
              version {
                  require("2.2.21")
              }
          }
      }
  }

  dependencies {
      constraints {
          add("implementation", "org.jetbrains.kotlin:kotlin-stdlib-jdk7") {
              version {
                  require("2.2.21")
              }
          }
          add("implementation", "org.jetbrains.kotlin:kotlin-stdlib-jdk8") {
              version {
                  require("2.2.21")
              }
          }
      }
  }

• Kotlin標準ライブラリバージョン 2.2.21 に対する依存関係（implementation("org.jetbrains.kotlin:kotlin-stdlib:2.2.21")）と、古いバージョン（1.8.0より前）のKotlin Gradleプラグインを使用している場合、標準ライブラリのバージョンに合わせてKotlin Gradleプラグインを更新してください。

  KotlinGroovy

  plugins {
      // `<...>` をプラグイン名に置き換えてください
      kotlin("<...>") version "2.2.21"
  }

  plugins {
      // `<...>` をプラグイン名に置き換えてください
      id "org.jetbrains.kotlin.<...>" version "2.2.21"
  }

• kotlin-stdlib-jdk7/kotlin-stdlib-jdk8の1.8.0より前のバージョン（例: implementation("org.jetbrains.kotlin:kotlin-stdlib-jdk7:SOME_OLD_KOTLIN_VERSION")）を使用しており、かつkotlin-stdlib:1.8+を遷移的に引き起こす依存関係がある場合は、kotlin-stdlib-jdk<7/8>:SOME_OLD_KOTLIN_VERSIONをkotlin-stdlib-jdk*:2.2.21に置き換えるか、それを引き起こすライブラリから遷移的なkotlin-stdlib:1.8+を除外してください。

  KotlinGroovy

  dependencies {
      implementation("com.example:lib:1.0") {
          exclude(group = "org.jetbrains.kotlin", module = "kotlin-stdlib")
      }
  }

  dependencies {
      implementation("com.example:lib:1.0") {
          exclude group: "org.jetbrains.kotlin", module: "kotlin-stdlib"
      }
  }

テストライブラリに依存関係を設定する

kotlin.test APIは、サポートされているすべてのプラットフォームでKotlinプロジェクトをテストするために利用できます。commonTestソースセットにkotlin-test依存関係を追加すると、Gradleプラグインが各テストソースセットに対応するテスト依存関係を推論できるようになります。

Kotlin/Nativeターゲットは追加のテスト依存関係を必要とせず、kotlin.test API実装は組み込まれています。

KotlinGroovy

kotlin {
    sourceSets {
        commonTest.dependencies {
            implementation(kotlin("test")) // これにより、すべてのプラットフォーム依存関係が自動的に追加されます
        }
    }
}

kotlin {
    sourceSets {
        commonTest {
            dependencies {
                implementation kotlin("test") // これにより、すべてのプラットフォーム依存関係が自動的に追加されます
            }
        }
    }
}

Kotlinモジュールへの依存関係には短縮形を使用できます。例えば、"org.jetbrains.kotlin:kotlin-test"にはkotlin("test")を使用します。

kotlin-test依存関係は、任意の共有ソースセットまたはプラットフォーム固有のソースセットでも使用できます。

kotlin-testのJVMバリアント

Kotlin/JVMの場合、GradleはデフォルトでJUnit 4を使用します。したがって、kotlin("test")依存関係はJUnit 4のバリアント、すなわちkotlin-test-junitに解決されます。

ビルドスクリプトのテストタスクで useJUnitPlatform()または useTestNG()を呼び出すことで、JUnit 5またはTestNGを選択できます。以下の例はKotlinマルチプラットフォームプロジェクトのものです。

KotlinGroovy

kotlin {
    jvm {
        testRuns["test"].executionTask.configure {
            useJUnitPlatform()
        }
    }
    sourceSets {
        commonTest.dependencies {
            implementation(kotlin("test"))
        }
    }
}

kotlin {
    jvm {
        testRuns["test"].executionTask.configure {
            useJUnitPlatform()
        }
    }
    sourceSets {
        commonTest {
            dependencies {
                implementation kotlin("test")
            }
        }
    }
}

以下の例はJVMプロジェクトのものです。

KotlinGroovy

dependencies {
    testImplementation(kotlin("test"))
}

tasks {
    test {
        useTestNG()
    }
}

dependencies {
    testImplementation 'org.jetbrains.kotlin:kotlin-test'
}

test {
    useTestNG()
}

JVMでJUnitを使用してコードをテストする方法を学ぶ。

自動JVMバリアント解決が設定に問題を引き起こす場合があります。その場合、必要なフレームワークを明示的に指定し、プロジェクトのgradle.propertiesファイルにこの行を追加することで自動解決を無効にできます。

kotlin.test.infer.jvm.variant=false

ビルドスクリプトでkotlin("test")のバリアントを明示的に使用していて、プロジェクトのビルドが互換性競合で動作しなくなった場合は、互換性ガイドのこの問題を参照してください。

kotlinxライブラリに依存関係を設定する

マルチプラットフォームライブラリを使用し、共有コードに依存する必要がある場合は、共有ソースセットで一度だけ依存関係を設定します。kotlinx-coroutines-coreやktor-client-coreなどのライブラリの基本アーティファクト名を使用してください。

KotlinGroovy

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.2")
        }
    }
}

kotlin {
    sourceSets {
        commonMain {
            dependencies {
                implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.2'
            }
        }
    }
}

プラットフォーム固有の依存関係のためにkotlinxライブラリが必要な場合でも、対応するプラットフォームソースセットでライブラリの基本アーティファクト名を使用できます。

KotlinGroovy

kotlin {
    sourceSets {
        jvmMain.dependencies {
            implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.2")
        }
    }
}

kotlin {
    sourceSets {
        jvmMain {
            dependencies {
                implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.2'
            }
        }
    }
}

リポジトリを宣言する

オープンソースの依存関係を使用するために、公開されているリポジトリを宣言できます。repositories{}ブロックで、リポジトリの名前を設定します。

KotlinGroovy

repositories {
    mavenCentral()
}

repositories {
    mavenCentral()
}

一般的なリポジトリはMaven CentralとGoogleのMavenリポジトリです。

Mavenプロジェクトも扱う場合、GradleとMavenプロジェクトを切り替える際に問題が発生する可能性があるため、mavenLocal()をリポジトリとして追加することを避けることをお勧めします。もしmavenLocal()リポジトリを追加する必要がある場合は、repositories{}ブロックの最後のリポジトリとして追加してください。詳細については、The case for mavenLocal()を参照してください。

複数のサブプロジェクトで同じリポジトリを宣言する必要がある場合は、settings.gradle(.kts)ファイルのdependencyResolutionManagement{}ブロックでリポジトリを一元的に宣言してください。

KotlinGroovy

dependencyResolutionManagement {
    repositories {
        mavenCentral()
    }
}

dependencyResolutionManagement {
    repositories {
        mavenCentral()
    }
}

サブプロジェクトで宣言されたリポジトリは、一元的に宣言されたリポジトリをオーバーライドします。この動作を制御する方法と利用可能なオプションに関する詳細については、Gradleのドキュメントを参照してください。

次のステップ

詳細については、以下を参照してください。

• コンパイラオプションとそれらを渡す方法。
• インクリメンタルコンパイル、キャッシュサポート、ビルドレポート、およびKotlinデーモン。
• Gradleの基礎と詳細。
• Gradleプラグインバリアントのサポート。