Gradle プロジェクトの構成

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

ビルドスクリプトの内容についての詳細は、 ビルドスクリプトの調査セクションを参照してください。

プラグインの適用

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

KotlinGroovy

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

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

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

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

KGP バージョン	Gradle の最小および最大バージョン	AGP の最小および最大バージョン
2.3.20–2.3.21	7.6.3–9.0.0	8.2.2–8.13.0
2.3.10	7.6.3–9.0.0	8.2.2–9.0.0
2.3.0	7.6.3–9.0.0	8.2.2–8.13.0
2.2.20–2.2.21	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

*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.3.0 では、プロジェクトのコンパイルに最小 Gradle バージョン 7.6.3 が必要です。

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

以前の KGP バージョン

KGP バージョン	Gradle の最小および最大バージョン	AGP の最小および最大バージョン
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 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	Kotlin データの .gradle ディレクトリへの書き込みを無効にするかどうかを制御します（古い IDEA バージョンとの後方互換性のため）。デフォルト：false

JVM をターゲットにする

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

KotlinGroovy

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

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

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

Kotlin および Java ソース

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

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

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

Java の .java ファイルを src/*/kotlin ディレクトリに保存しないでください。これらの .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 ターゲットの追加設定がないデフォルトの構成を考えてみましょう。

KotlinGroovy

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

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

ビルドスクリプトに jvmTarget の値に関する明示的な情報がない場合、そのデフォルト値は null となり、コンパイラはそれをデフォルト値の 1.8 として扱います。targetCompatibility は現在の Gradle の JDK バージョンと等しくなります。これは（Java ツールチェーンのアプローチを使用しない限り）使用している JDK バージョンと同じです。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 を自動検出し、ビルドに必要な不足している 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>))
    }
    // またはより短く：
    jvmToolchain(<MAJOR_JDK_VERSION>)
    // 例えば：
    jvmToolchain(17)
}

kotlin {
    jvmToolchain {
        languageVersion = JavaLanguageVersion.of(<MAJOR_JDK_VERSION>)
    }
    // またはより短く：
    jvmToolchain(<MAJOR_JDK_VERSION>)
    // 例えば：
    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 がどのツールチェーンを使用しているかを把握するには、Gradle ビルドをログレベル --info で実行し、出力の中で [KOTLIN] Kotlin compilation 'jdkHome' argument: で始まる文字列を探してください。コロンの後の部分がツールチェーンの JDK バージョンになります。

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

Kotlin プラグインにおける Gradle JVM ツールチェーンサポートの詳細についてはこちらを参照してください。

タスク DSL による JDK バージョンの設定

タスク 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
    )
}

コンパイルタスクの関連付け

コンパイルを関連付け（Associate）し、あるコンパイルが別のコンパイルのコンパイル済み出力を使用するように関係を設定できます。コンパイルを関連付けることで、それらの間に 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 モジュール (JPMS) を有効にした構成

Kotlin Gradle プラグインを Java モジュール (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 {
        // javac にコンパイル済みの Kotlin クラスを提供します。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() {
            // javac にコンパイル済みの Kotlin クラスを提供します。Java/Kotlin 混合ソースを動作させるために必要です
            return ["--patch-module", "YOUR_MODULE_NAME=${sourceSets["main"].output.asPath}"]
        }
    })
}

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

モジュールの場合、Kotlin ファイル内のパッケージ名は module-info.java のパッケージ名と一致させる必要があります。そうしないと、「パッケージが空であるか存在しない」というビルドエラーが発生します。

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

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

その他の詳細

コンパイルタスクでのアーティファクト使用の無効化

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

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.kotlin.classesDirectories を sourceSets.main.outputs に明示的に追加する必要があります。

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.3.0"
}

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

さまざまなプラットフォーム向けの 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 のコードベースと共有する
• Kotlin で共有不可能な Web アプリを構築する

詳細については、Web 開発を参照してください。

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

KotlinGroovy

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

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

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

kotlin {
    js().browser {  // または js().nodejs
        /* ... */
    }
}

JavaScript 用の Gradle 構成の詳細を参照し、Kotlin/JS プロジェクトの設定についてさらに学んでください。

WebAssembly をターゲットにする

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

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

KotlinGroovy

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

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

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

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

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

kotlin {
    wasmJs {
        browser { // または nodejs
            /* ... */
        }
    }
}

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

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

Wasm 用の Gradle 構成の詳細を参照してください。

Web ターゲットにおける Kotlin および Java ソース

KGP は Kotlin ファイルに対してのみ動作するため、（プロジェクトに Java ファイルが含まれている場合は）Kotlin ファイルと 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 プロパティで無効にできます。

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

バージョンをアラインするその他の方法

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

  KotlinGroovy

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

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

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

  KotlinGroovy

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

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

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

  KotlinGroovy

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

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

• 1.8.0 より前のバージョンの kotlin-stdlib-jdk7/kotlin-stdlib-jdk8（例：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.3.0 に置き換えるか、それを持ち込むライブラリから推移的な 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 プロジェクトのテストに利用できます。 Gradle プラグインが各テストソースセットに対して対応するテスト依存関係を推論できるように、kotlin-test 依存関係を commonTest ソースセットに追加します。

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 Multiplatform プロジェクトの場合です。

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's Maven repository があります。

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

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

KotlinGroovy

dependencyResolutionManagement {
    repositories {
        mavenCentral()
    }
}

dependencyResolutionManagement {
    repositories {
        mavenCentral()
    }
}

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

Experimental

生成されたソースの登録

生成されたソースを登録すると、IDE、サードパーティプラグイン、その他のツールが、生成されたコードと通常のソースファイルを区別しやすくなります。これにより、IDE などのツールが UI 上で生成されたコードを強調表示したり、プロジェクトのインポート時に生成タスクをトリガーしたりするのに役立ちます。生成されたソースを登録するには、KotlinSourceSet インターフェースを使用します。

Kotlin ファイルを含むディレクトリを登録するには、build.gradle.kts ファイルで SourceDirectorySet 型の generatedKotlin プロパティを使用します。例：

val generatorTask = project.tasks.register("generator") {
    val outputDirectory = project.layout.projectDirectory.dir("src/main/kotlinGen")
    outputs.dir(outputDirectory)
    doLast {
        outputDirectory.file("generated.kt").asFile.writeText(
            // language=kotlin
            """
            fun printHello() {
                println("hello")
            }
            """.trimIndent()
        )
    }
}

kotlin.sourceSets.getByName("main").generatedKotlin.srcDir(generatorTask)

この例では、出力ディレクトリを "src/main/kotlinGen" とする新しいタスク generator を作成します。タスクが実行されると、doLast {} タスクアクションによって出力ディレクトリに generated.kt ファイルが作成されます。最後に、このタスクの出力を生成されたソースとして登録します。

Gradle プラグインを開発している場合は、allKotlinSources プロパティを使用して、KotlinSourceSet.kotlin および KotlinSourceSet.generatedKotlin プロパティに登録されているすべてのソースにアクセスできます。

次のステップ

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

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