Skip to content

Gradle プロジェクトの構成 ​

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

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

プラグインの適用 ​

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

kotlin
plugins {
    // Replace `<...>` with the plugin name appropriate for your target environment
    kotlin("<...>") version "2.4.21"
    // For example, if your target environment is JVM:
    // kotlin("jvm") version "2.4.21"
}
groovy
plugins {
    // Replace `<...>` with the plugin name appropriate for your target environment
    id 'org.jetbrains.kotlin.<...>' version '2.4.21'
    // For example, if your target environment is JVM: 
    // id 'org.jetbrains.kotlin.jvm' version '2.4.21'
}

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

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

KGP バージョンGradle の最小/最大バージョンAGP の最小/最大バージョン
2.4.20–2.4.217.6.3–9.7.08.5.2–9.3.1
2.4.0–2.4.107.6.3–9.5.08.5.2–9.1.0
2.3.20–2.3.217.6.3–9.3.08.2.2–9.0.0
2.3.107.6.3–9.0.08.2.2–9.0.0
2.3.07.6.3–9.0.08.2.2–8.13.0
2.2.20–2.2.217.6.3–8.147.3.1–8.11.1
2.2.0–2.2.107.6.3–8.147.3.1–8.10.0
2.1.20–2.1.217.6.3–8.12.17.3.1–8.7.2
2.1.0–2.1.107.6.3–8.10*7.3.1–8.7.2
2.0.20–2.0.216.8.3–8.8*7.1.3–8.5
2.0.06.8.3–8.57.1.3–8.3.1
1.9.20–1.9.256.8.3–8.1.14.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.4.21 では、プロジェクトをコンパイルするために最低でも 7.6.3 の Gradle バージョンが必要です。

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

過去の KGP バージョン ​

KGP バージョンGradle の最小/最大バージョンAGP の最小/最大バージョン
1.9.0–1.9.106.8.3–7.6.04.2.2–7.4.0
1.8.20–1.8.226.8.3–7.6.04.1.3–7.4.0
1.8.0–1.8.116.8.3–7.3.34.1.3–7.2.1
1.7.20–1.7.226.7.1–7.1.13.6.4–7.0.4
1.7.0–1.7.106.7.1–7.0.23.4.3–7.0.2
1.6.20–1.6.216.1.1–7.0.23.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.disableWriteKotlin データの .gradle ディレクトリへの書き込みを無効にするかどうかを制御します(古い IDEA バージョンとの下位互換性のため)。デフォルト: false

JVM をターゲットにする ​

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

kotlin
plugins {
    kotlin("jvm") version "2.4.21"
}
groovy
plugins {
    id "org.jetbrains.kotlin.jvm" version "2.4.21"
}

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

Kotlin および Java のソース ​

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

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

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

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

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

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

kotlin
sourceSets.main {
    java.srcDirs("src/main/myJava", "src/main/myKotlin")
}
groovy
sourceSets {
    main.kotlin.srcDirs += 'src/main/myKotlin'
    main.java.srcDirs += 'src/main/myJava'
}

ビルドモジュール内には、次のような関連するコンパイルタスクが存在する場合があります:

  • 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) ファイル内のタスクレベルで構成することも可能です:

kotlin
tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinJvmCompile>().configureEach {
    jvmTargetValidationMode.set(org.jetbrains.kotlin.gradle.dsl.jvm.JvmTargetValidationMode.WARNING)
}
groovy
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 ターゲットに関する追加設定がないデフォルトの構成を考えてみましょう:

kotlin
plugins {
    kotlin("jvm") version "2.4.21"
}
groovy
plugins {
    id "org.jetbrains.kotlin.jvm" version "2.4.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 からです。 しかしながら、この問題のため、バージョン 8.1.0-alpha09 になるまで、AGP は targetCompatibility をツールチェーンの JDK と同じになるように設定していませんでした。 8.1.0-alpha09 未満のバージョンを使用している場合は、compileOptions を介して手動で targetCompatibility を構成する必要があります。 プレースホルダー <MAJOR_JDK_VERSION> を使用したい JDK バージョンに置き換えてください:

kotlin
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 バージョンに置き換えてください:

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

kotlin エクステンション経由でツールチェーンを設定すると、Java のコンパイルタスクのツールチェーンも更新されることに注意してください。

java エクステンション経由でツールチェーンを設定することもでき、その場合 Kotlin のコンパイルタスクもそれを使用します:

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

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

kotlin
plugins {
    id("org.gradle.toolchains.foojay-resolver-convention") version("1.0.0")
}
groovy
plugins {
    id 'org.gradle.toolchains.foojay-resolver-convention' version '1.0.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> プレースホルダーを置き換えてください:

kotlin
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)
}
groovy
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 バージョンに置き換えることもできます:

kotlin
tasks.withType<UsesKotlinJavaToolchain>().configureEach {
    kotlinJavaToolchain.jdk.use(
        "/path/to/local/jdk", // Put a path to your JDK
        JavaVersion.<LOCAL_JDK_VERSION> // For example, JavaVersion.17
    )
}

コンパイラタスクの関連付け(Associate) ​

一方のコンパイルが他方のコンパイル済み出力を利用するようにコンパイル間の関係を設定することで、コンパイル同士を「関連付け(associate)」できます。コンパイルを関連付けることで、それらの間に internal 可視性が確立されます。

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

ソースセット間の可視性を推論するために IDE に関連付けられたコンパイルをサポートさせるには、build.gradle(.kts) に次のコードを追加します:

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

ここでは、integrationTest コンパイルが main コンパイルに関連付けられており、機能テストから internal オブジェクトへのアクセスが可能になっています。

Java モジュール(JPMS)を有効にした構成 ​

Kotlin Gradle プラグインを Java モジュール と連携させるには、ビルドスクリプトに以下の行を追加し、YOUR_MODULE_NAME を JPMS モジュールの参照(例えば org.company.module)に置き換えてください:

kotlin
tasks.named("compileJava", JavaCompile::class.java) {
    // Provide compiled Kotlin classes to javac – needed for Java/Kotlin mixed sources to work
    val mainOutput: FileCollection = sourceSets["main"].output
    options.compilerArgumentProviders.add(CommandLineArgumentProvider {
        listOf("--patch-module", "YOUR_MODULE_NAME=${mainOutput.asPath}")
    })
}
groovy
tasks.named("compileJava", JavaCompile.class) {
    // Provide compiled Kotlin classes to javac – needed for Java/Kotlin mixed sources to work
    FileCollection mainOutput = sourceSets["main"].output
    options.compilerArgumentProviders.add(new CommandLineArgumentProvider() {
        @Override
        Iterable<String> asArguments() {
            return ["--patch-module", "YOUR_MODULE_NAME=${mainOutput.asPath}"]
        }
    })
}

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

モジュールの場合、「パッケージが空であるか存在しません(package is empty or does not exist)」というビルドエラーを防ぐため、Kotlin ファイル内のパッケージ名は module-info.java のパッケージ名と同じにする必要があります。

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

その他の詳細 ​

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

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

none
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
kotlin.build.archivesTaskOutputAsFriendModule=false

Kotlin/JVM タスクの遅延作成 ​

Kotlin 1.8.20 以降、Kotlin Gradle プラグインはすべてのタスクを登録(register)し、ドライラン(dry run)時にはそれらを構成(configure)しません。

コンパイルタスクの destinationDirectory の非デフォルト配置 ​

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

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

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

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

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

kotlin
plugins {
    kotlin("multiplatform") version "2.4.21"
}
groovy
plugins {
    id 'org.jetbrains.kotlin.multiplatform' version '2.4.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 コードベースとビジネスロジックを共有する
  • Kotlin で共有不可(単独)の Web アプリケーションを構築する

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

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

kotlin
plugins {
    kotlin("multiplatform") version "2.4.21"
}
groovy
plugins {
    id 'org.jetbrains.kotlin.multiplatform' version '2.4.21'
}

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

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

WebAssembly をターゲットにする ​

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

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

kotlin
plugins {
    kotlin("multiplatform") version "2.4.21"
}
groovy
plugins {
    id 'org.jetbrains.kotlin.multiplatform' version '2.4.21'
}

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

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

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

WASI 環境向けには、Node.js または Wasmtime を指定して wasmWasi ターゲットを構成します:

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

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

KGP は Kotlin ファイルに対してのみ機能するため、(プロジェクトに Java ファイルが含まれている場合は)Kotlin ファイルと Java ファイルを分けておくことが推奨されます。別々に配置しない場合は、sourceSets{} ブロックでソースフォルダーを指定してください:

kotlin
kotlin {
    sourceSets["main"].apply {
        kotlin.srcDir("src/main/myKotlin")
    }
}
groovy
kotlin {
    sourceSets {
        main.kotlin.srcDirs += 'src/main/myKotlin'
    }
}

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

Kotlin Gradle プラグイン(JVM、JS、Multiplatform、Native など)のいずれかが適用されたときに常に何らかの構成アクションをトリガーするには、すべての Kotlin プラグインが継承している KotlinBasePlugin インターフェースを使用します:

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

// ...

project.plugins.withType<KotlinBasePlugin>() {
    // Configure your action here
}
groovy
import org.jetbrains.kotlin.gradle.plugin.KotlinBasePlugin

// ...

project.plugins.withType(KotlinBasePlugin.class) {
    // Configure your action here
}

依存関係の構成 ​

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

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

トップレベルでの依存関係の構成

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

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

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

プラットフォーム固有の依存関係は、対応するターゲットの 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 プロパティを追加できます:

none
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 プロパティを設定することで無効化できます:

none
kotlin.stdlib.jdk.variants.version.alignment=false
バージョンをアラインさせるその他の方法 ​
  • バージョンアラインメントに問題がある場合は、Kotlin BOM を使用してすべてのバージョンを一致させることができます。ビルドスクリプトで kotlin-bom へのプラットフォーム依存関係を宣言します:

    kotlin
    implementation(platform("org.jetbrains.kotlin:kotlin-bom:2.4.21"))
    groovy
    implementation platform('org.jetbrains.kotlin:kotlin-bom:2.4.21')
  • 標準ライブラリのバージョンに対する依存関係を追加していないものの、2 つの異なる依存関係が推移的に異なる古いバージョンの Kotlin 標準ライブラリを取り込んでいる場合、それらの推移的ライブラリに対して 2.4.21 バージョンを明示的に要求できます:

    kotlin
    dependencies {
        constraints {
            add("implementation", "org.jetbrains.kotlin:kotlin-stdlib-jdk7") {
                version {
                    require("2.4.21")
                }
            }
            add("implementation", "org.jetbrains.kotlin:kotlin-stdlib-jdk8") {
                version {
                    require("2.4.21")
                }
            }
        }
    }
    groovy
    dependencies {
        constraints {
            add("implementation", "org.jetbrains.kotlin:kotlin-stdlib-jdk7") {
                version {
                    require("2.4.21")
                }
            }
            add("implementation", "org.jetbrains.kotlin:kotlin-stdlib-jdk8") {
                version {
                    require("2.4.21")
                }
            }
        }
    }
  • Kotlin 標準ライブラリバージョン 2.4.21 への依存関係(implementation("org.jetbrains.kotlin:kotlin-stdlib:2.4.21"))を追加しており、Kotlin Gradle プラグインの古いバージョン(1.8.0 未満)を使用している場合は、標準ライブラリのバージョンに合わせて Kotlin Gradle プラグインを更新してください:

    kotlin
    plugins {
        // replace `<...>` with the plugin name
        kotlin("<...>") version "2.4.21"
    }
    groovy
    plugins {
        // replace `<...>` with the plugin name
        id "org.jetbrains.kotlin.<...>" version "2.4.21"
    }
  • 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.4.21 に置き換えるか、それを取り込むライブラリから推移的な kotlin-stdlib:1.8+ を除外(exclude)してください:

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

テストライブラリへの依存関係の設定 ​

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

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

kotlin
kotlin {
    sourceSets {
        commonTest.dependencies {
            implementation(kotlin("test")) // This brings all the platform dependencies automatically
        }
    }
}
groovy
kotlin {
    sourceSets {
        commonTest {
            dependencies {
                implementation kotlin("test") // This brings all the platform dependencies automatically
            }
        }
    }
}

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 プロジェクト用のものです:

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

以下の例は、JVM プロジェクト用のものです:

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

tasks {
    test {
        useTestNG()
    }
}
groovy
dependencies {
    testImplementation 'org.jetbrains.kotlin:kotlin-test'
}

test {
    useTestNG()
}

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

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

text
kotlin.test.infer.jvm.variant=false

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

kotlinx ライブラリへの依存関係の設定 ​

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

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

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

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

リポジトリの宣言 ​

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

kotlin
repositories {
    mavenCentral()
}
groovy
repositories {
    mavenCentral()
}

代表的なリポジトリには Maven Central や Google の Maven リポジトリ があります。

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

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

kotlin
dependencyResolutionManagement {
    repositories {
        mavenCentral()
    }
}
groovy
dependencyResolutionManagement {
    repositories {
        mavenCentral()
    }
}

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

Experimental

生成されたソースの登録

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

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

kotlin
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 プロパティに登録されているすべてのソースにアクセスできます。

次のステップ ​

以下についてさらに詳しく学びましょう: