メインコンテンツまでスキップ

Gradleプロジェクトの構成

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

注記

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

プラグインの適用​

Kotlin Gradle pluginを適用するには、Gradle plugins DSLのplugins{} ブロックを使用します。

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

Kotlin Gradle plugin (KGP) とKotlinは、同じバージョン番号を共有します。

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

KGP versionGradle min and max versionsAGP min and max versions
2.1.207.6.3–8.117.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
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 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 pluginを使用している場合、 JVMターゲットでwithJava()関数を呼び出すマルチプラットフォームプロジェクトに非推奨の警告が表示されることがあります。 詳細については、デフォルトで作成されるJavaソースセットをご覧ください。

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

たとえば、Kotlin Gradle pluginとkotlin-multiplatform plugin 2.1.20では、プロジェクトのコンパイルに最低限Gradle バージョン7.6.3が必要です。

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

プロジェクト内のKotlin Gradle pluginデータ​

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

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

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

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

JVMをターゲットにする​

JVMをターゲットにするには、Kotlin JVM pluginを適用します。

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

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

KotlinとJavaのソース​

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

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

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

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

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

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

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

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

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

  • compileKotlinとcompileJava
  • compileTestKotlinとcompileTestJava

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

このような関連タスクの場合、Kotlin Gradle pluginはJVMターゲットの互換性をチェックします。kotlin拡張機能またはタスクのjvmTarget属性と、java拡張機能またはタスクのtargetCompatibilityの値が異なると、JVMターゲットの非互換が発生します。例： compileKotlinタスクのjvmTarget=1.8で、 compileJavaタスクが（または継承）targetCompatibility=15の場合。

build.gradle(.kts)ファイルのkotlin.jvm.target.validation.modeプロパティを設定して、プロジェクト全体のこのチェックの動作を構成します。

  • error – pluginはビルドを失敗させます。Gradle 8.0以降のプロジェクトのデフォルト値です。
  • warning – pluginは警告メッセージを出力します。Gradle 8.0より前のプロジェクトのデフォルト値です。
  • ignore – pluginはチェックをスキップし、メッセージを生成しません。

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

tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinJvmCompile>().configureEach {
    jvmTargetValidationMode.set(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 pluginのみがあり、JVMターゲットに追加の設定がない場合のJVMターゲットのデフォルト構成を検討してみましょう。

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

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

Gradle Java toolchains support​

注記

Androidユーザーへの警告。Gradle toolchain supportを使用するには、Android Gradle plugin (AGP) バージョン8.1.0-alpha09以降を使用してください。

Gradle Java toolchain supportは、AGP 7.4.0以降で利用可能です。 ただし、この問題のため、AGPはバージョン8.1.0-alpha09までtoolchainのJDKと等しくなるようにtargetCompatibilityを設定しませんでした。 8.1.0-alpha09より前のバージョンを使用する場合は、compileOptionsを使用してtargetCompatibilityを手動で構成する必要があります。 プレースホルダー<MAJOR_JDK_VERSION>を使用するJDKバージョンに置き換えます。

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

Gradle 6.7はJava toolchains supportを導入しました。 この機能を使用すると、次のことができます。

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

toolchains supportを使用すると、GradleはローカルJDKを自動検出し、Gradleがビルドに必要な不足しているJDKをインストールできます。 これで、Gradle自体は任意のJDKで実行でき、メジャーJDKバージョンに依存するタスクのリモートビルドキャッシュ機能を再利用できます。

Kotlin Gradle pluginは、Kotlin/JVMコンパイルタスクのJava toolchainsをサポートしています。JSおよびNativeタスクはtoolchainsを使用しません。 Kotlinコンパイラは常にGradleデーモンが実行されているJDKで実行されます。 Java toolchain：

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

次のコードを使用してtoolchainを設定します。プレースホルダー<MAJOR_JDK_VERSION>を使用するJDKバージョンに置き換えます。

kotlin {
    jvmToolchain {
        languageVersion.set(JavaLanguageVersion.of(<MAJOR_JDK_VERSION>))
    }
    // またはより短く：
    jvmToolchain(<MAJOR_JDK_VERSION>)
    // 例：
    jvmToolchain(17)
}

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

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

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

Gradle 8.0.2以降を使用する場合は、toolchain resolver pluginも追加する必要があります。 このタイプのpluginは、toolchainをダウンロードするリポジトリを管理します。例として、settings.gradle(.kts)に次のpluginを追加します。

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

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

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

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

Kotlin pluginでのGradle JVM toolchain supportの詳細をご覧ください。

Task DSLを使用してJDKバージョンを設定する​

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

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)
}

または、ローカル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)に追加します。

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

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

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

Kotlin Gradle pluginがJava Modulesで動作するようにするには、 ビルドスクリプトに次の行を追加し、YOUR_MODULE_NAMEをJPMSモジュールへの参照（たとえば、 org.company.module）に置き換えます。

// 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}")
    })
}
注記

通常どおり、module-info.javaをsrc/main/javaディレクトリに配置します。

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

詳細については、以下をご覧ください。

その他の詳細​

Kotlin/JVMの詳細をご覧ください。

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

まれなシナリオでは、循環依存関係エラーが原因でビルドが失敗する可能性があります。たとえば、1つのコンパイルが別のコンパイルのすべての内部宣言を表示でき、生成されたアーティファクト が両方のコンパイルタスクの出力に依存している場合などです。

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 pluginはすべてのタスクを登録し、ドライランでは構成しません。

コンパイルタスクのdestinationDirectoryのデフォルト以外の場所​

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

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

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

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

注記

kotlin-multiplatform pluginは、Gradle 7.6.3以降で動作します。

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

さまざまなプラットフォーム向けのKotlin Multiplatformと、 iOSおよびAndroid向けのKotlin Multiplatformの詳細をご覧ください。

Androidをターゲットにする​

Androidアプリケーションの作成には、Android Studioを使用することをお勧めします。Android Gradle pluginの使用方法をご覧ください。

JavaScriptをターゲットにする​

JavaScriptをターゲットにする場合は、kotlin-multiplatform pluginも使用します。Kotlin/JSプロジェクトの設定の詳細をご覧ください

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

JavaScriptのKotlinとJavaのソース​

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

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

KotlinBasePluginインターフェースを使用した構成アクションのトリガー​

Kotlin Gradle plugin（JVM、JS、Multiplatform、Nativeなど）が適用されるたびに、何らかの構成アクションをトリガーするには、すべてのKotlin pluginが継承するKotlinBasePluginインターフェースを使用します。

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

// ...

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

依存関係の構成​

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

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

または、トップレベルで依存関係を設定することもできます。

依存関係のタイプ​

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

TypeDescriptionWhen to use

api

コンパイル時と実行時の両方で使用され、ライブラリの利用者にエクスポートされます。

依存関係の型が現在のモジュールのパブリックAPIで使用されている場合は、api依存関係を使用します。

implementation

現在のモジュールのコンパイル時と実行時に使用されますが、implementation依存関係を持つモジュールに依存する他のモジュールのコンパイルには公開されません。

モジュールの内部ロジックに必要な依存関係に使用します。

モジュールが公開されていないエンドポイントアプリケーションである場合は、api依存関係ではなくimplementation依存関係を使用します。

compileOnly

現在のモジュールのコンパイルに使用され、実行時や他のモジュールのコンパイル時には使用できません。

実行時にサードパーティの実装が利用可能なAPIに使用します。

runtimeOnly

実行時に使用できますが、モジュールのコンパイル時には表示されません。

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

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

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

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

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

kotlin.stdlib.default.dependency=false

推移的な依存関係のバージョンアライメント​

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

Kotlin標準ライブラリのバージョン1.8.0〜1.9.10の依存関係を追加する場合は、たとえば、implementation("org.jetbrains.kotlin:kotlin-stdlib:1.8.0")の場合、Kotlin Gradle Pluginは、このKotlinバージョンを 推移的なkotlin-stdlib-jdk7およびkotlin-stdlib-jdk8依存関係に使用します。これにより、異なる標準ライブラリバージョンからのクラスの重複を回避できます。[kotlin-stdlib-jdk7と`kotlin-stdlib-jdk