build.gradle.kts書き方｜Groovy対応表とバージョンカタログ

build.gradle.kts は、Gradle のビルド設定を Kotlin で書いたファイルです。 Groovy の build.gradle との違いは「文字列はダブルクォートだけ」「代入は必ず =」「関数呼び出しは必ず ( )」の3つが中心です。書き換えの早見表を先に載せます。

依存のバージョンは gradle/libs.versions.toml（Version Catalog）にまとめ、libs.〜 で参照するのが、Gradle の公式ドキュメントで勧められている書き方です。gradle init で作ったプロジェクトも、この形になっていました。

確認環境：Gradle 8.14.3（同梱の Kotlin 2.0.21）・OpenJDK 21.0.10・Linux で、外部の依存を使わない Java プロジェクトを Groovy 版と Kotlin 版で作り、同じ結果になることと、書き換えの誤りで出るエラー文を確かめました。Gradle の最新版は 9.8.1（2026年10月7日公開、gradle.org のリリース一覧）です。Gradle 9 系の仕様、Spring Boot・Kotlin プラグインの書き方は、Gradle・Spring Boot・kotlinlang.org のドキュメントで確かめました（確認日 2026年10月12日）。

build.gradle.kts とは

Gradle のビルドスクリプトは、Groovy でも Kotlin でも書けます。Kotlin で書くときはファイル名の最後に .kts（Kotlin Script）を付けます。

gradle init --use-defaults で Java アプリを作ると、Gradle 8.14.3 では build.gradle.kts と settings.gradle.kts ができました。新しいプロジェクトの既定は Kotlin DSL です。

Groovy 版と Kotlin 版のファイルは、同じビルドの中に混ぜられます。1ファイルずつ書き換えられます。Maven（pom.xml）の書き方は、関連記事「Mavenコマンド一覧｜pom.xml書き方とよく使うオプション」で扱っています。

Groovy と Kotlin を同じ内容で並べる

同じ動きをする2つのファイルを作り、gradle hello run jar を実行しました。どちらも同じ出力と同じ jar になりました。

// build.gradle（Groovy）
plugins {
    id 'application'
}

group 'com.example'
version libs.versions.app.get()

ext {
    appEnv = 'dev'
}
ext.buildBy = 'groovy'

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
    }
}

application {
    mainClass = 'demo.App'
}

tasks.named('run') {
    systemProperty 'app.env', appEnv
}

tasks.named('jar') {
    archiveFileName = "demo-${version}.jar"
    manifest {
        attributes 'Main-Class': 'demo.App', 'Built-By': buildBy
    }
}

tasks.withType(JavaCompile).configureEach {
    options.encoding = 'UTF-8'
}

tasks.register('hello') {
    group = 'demo'
    description = 'あいさつを表示する'
    def v = project.version
    def env = appEnv
    doLast {
        println "hello ${v} env=${env}"
    }
}

// build.gradle.kts（Kotlin）
plugins {
    application
}

group = "com.example"
version = libs.versions.app.get()

val appEnv by extra("dev")
extra["buildBy"] = "kotlin"

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
    }
}

application {
    mainClass = "demo.App"
}

tasks.named<JavaExec>("run") {
    systemProperty("app.env", appEnv)
}

tasks.jar {
    archiveFileName = "demo-$version.jar"
    manifest {
        attributes("Main-Class" to "demo.App", "Built-By" to project.extra["buildBy"])
    }
}

tasks.withType<JavaCompile>().configureEach {
    options.encoding = "UTF-8"
}

tasks.register("hello") {
    group = "demo"
    description = "あいさつを表示する"
    val v = project.version
    val env = appEnv
    doLast {
        println("hello $v env=$env")
    }
}

$ gradle -q hello run jar
hello 1.2.0 env=dev
Hello from dev

$ unzip -p build/libs/demo-1.2.0.jar META-INF/MANIFEST.MF
Manifest-Version: 1.0
Main-Class: demo.App
Built-By: kotlin

tasks.jar { } の中で extra["buildBy"] と書くと、最初は失敗しました。 ブロックの中の extra は「jar タスクの追加プロパティ」を指すためです。プロジェクトのものは project.extra[…] と書きます（エラー文は後述）。

書き換えの対応表（詳しい版）

文字列・代入・関数呼び出し

Gradle のドキュメントでは、書き換えるときは「まず全部を = の代入として書き、コンパイルエラーになったものを関数呼び出しに直す」順番が勧められています。

plugins

plugins { } で入れたプラグインだけ、java { }・application { }・tasks.jar などの書き方（型付きのアクセサ）が使えます。 apply(plugin = "application") で入れると、後の application { } が Unresolved reference になりました。Gradle のドキュメントでも「apply() 関数より plugins {} ブロックを強く勧める」とあります。

dependencies

implementation などの名前は、プラグインが作る「構成（configuration）」です。自分で作った構成は、plugins { } の後で作られるため型付きのアクセサがありません。ドキュメントでは、文字列で "db"("org.postgresql:postgresql") のように書く方法が示されています。

ext と extra（追加プロパティ）

Groovy の書き方のまま ext.appEnv = "dev" と書くと、Unresolved reference: appEnv で止まりました。ext 自体は Kotlin からも見えますが、その先の名前は型で決まっていないためです。値を一か所にまとめたいだけなら、ext より Version Catalog（後述）か gradle.properties のほうが Kotlin DSL と相性がよいと言えます。

tasks

tasks.named("run") のように型を書かないと、Task として扱われます。 systemProperty のような JavaExec だけの関数は Unresolved reference: systemProperty になりました。タスクの型は gradle help --task run で調べられます（ドキュメントの方法）。

プロパティへの代入（= と .set()）

Gradle の新しいプロパティ（Property<T> 型）は、昔は .set() で入れていました。Kotlin DSL のドキュメントでは「= 演算子が set() を呼ぶ好ましい書き方」とされています。

application {
    mainClass.set("demo.App")   // 以前の書き方
    mainClass = "demo.App"      // 今の書き方（同じ意味）
}

上の Kotlin 版のビルドでは、mainClass・archiveFileName・languageVersion を = で書いて、Gradle 8.14.3 で通りました。

Version Catalog（libs.versions.toml）の雛形

gradle/libs.versions.toml を置くと、Gradle が自動で読み込み、libs という名前で使えるようにします。

# gradle/libs.versions.toml
[versions]
kotlin = "2.4.21"
spring-boot = "4.1.1"
spring-dependency-management = "1.1.7"
junit = "5.13.4"
mockk = "1.14.11"

[libraries]
# バージョンを [versions] から参照する
mockk = { module = "io.mockk:mockk", version.ref = "mockk" }
junit-bom = { module = "org.junit:junit-bom", version.ref = "junit" }
# BOM で決まるものはバージョンを書かない
junit-jupiter = { module = "org.junit.jupiter:junit-jupiter" }
junit-platform-launcher = { module = "org.junit.platform:junit-platform-launcher" }

[bundles]
# まとめて足すもの
test-basics = ["junit-jupiter", "mockk"]

[plugins]
kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin" }
kotlin-spring = { id = "org.jetbrains.kotlin.plugin.spring", version.ref = "kotlin" }
kotlin-jpa = { id = "org.jetbrains.kotlin.plugin.jpa", version.ref = "kotlin" }
spring-boot = { id = "org.springframework.boot", version.ref = "spring-boot" }
spring-dependency-management = { id = "io.spring.dependency-management", version.ref = "spring-dependency-management" }

名前の付け方と変換

別名のハイフン（-）とアンダースコア（_）は、ドット（.）に変わります。 junit-jupiter は libs.junit.jupiter、spring-boot は libs.plugins.spring.boot です。

依存の座標が実際に何になるか、タスクで表示して確かめました。

tasks.register("showLibs") {
    val bom = libs.junit.bom.get().toString()
    val jupiter = libs.junit.jupiter.get().toString()
    val junitVer = libs.versions.junit.get()
    doLast {
        println("bom=$bom")
        println("jupiter=$jupiter")
        println("junit version=$junitVer")
    }
}

bom=org.junit:junit-bom:5.13.4
jupiter=org.junit.jupiter:junit-jupiter
junit version=5.13.4

使えない名前・できないこと

ドキュメントにある制約です。

予約された先頭語を使った versions-dependency = … を足すと、次のエラーになりました。

Invalid catalog definition:
  - Problem: In version catalog libs, alias 'versions-dependency' is not a valid alias.
    Reason: Prefix for dependency shouldn't be equal to 'versions'.
    Possible solution: Use a different alias which prefix is not equal to 'bundles', 'plugins', or 'versions'.

Kotlin/JVM 用 build.gradle.kts 全文

plugins {
    alias(libs.plugins.kotlin.jvm)
    application
}

group = "com.example"
version = "0.1.0"

repositories {
    mavenCentral()
}

dependencies {
    testImplementation(kotlin("test"))
    testImplementation(platform(libs.junit.bom))
    testImplementation(libs.bundles.test.basics)
    testRuntimeOnly(libs.junit.platform.launcher)
}

kotlin {
    jvmToolchain(21)
}

application {
    mainClass = "com.example.MainKt"
}

tasks.test {
    useJUnitPlatform()
}

kotlinlang.org の対応表では、Kotlin Gradle プラグイン 2.4.20〜2.4.21 が対応する Gradle は 7.6.3〜9.7.0 です。MockK の使い方は、関連記事「MockK 使い方｜every・verify・coEveryとMockito対応表」で扱っています。

Spring Boot（Kotlin）用 build.gradle.kts 全文

Spring Boot 4.1.1 のドキュメントでは、使える Gradle は「8.x（8.14 以降）と 9.x」、Java は 17 以上です。

plugins {
    alias(libs.plugins.kotlin.jvm)
    alias(libs.plugins.kotlin.spring)
    alias(libs.plugins.kotlin.jpa)
    alias(libs.plugins.spring.boot)
    alias(libs.plugins.spring.dependency.management)
}

group = "com.example"
version = "0.0.1-SNAPSHOT"

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
    }
}

repositories {
    mavenCentral()
}

dependencies {
    // Spring Boot が版を決めるものは、版を書かずに文字列で書く
    implementation("org.springframework.boot:spring-boot-starter-webmvc")
    implementation("org.springframework.boot:spring-boot-starter-data-jpa")
    implementation("org.springframework.boot:spring-boot-starter-validation")
    implementation("tools.jackson.module:jackson-module-kotlin")
    implementation("org.jetbrains.kotlin:kotlin-reflect")
    runtimeOnly("com.h2database:h2")

    testImplementation("org.springframework.boot:spring-boot-starter-webmvc-test")
    testImplementation("org.jetbrains.kotlin:kotlin-test-junit5")
    testImplementation(libs.mockk)
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}

kotlin {
    compilerOptions {
        freeCompilerArgs.addAll("-Xjsr305=strict")
    }
}

allOpen {
    annotation("jakarta.persistence.Entity")
    annotation("jakarta.persistence.MappedSuperclass")
    annotation("jakarta.persistence.Embeddable")
}

tasks.withType<Test> {
    useJUnitPlatform()
}

kotlin-spring・kotlin-jpa が要る理由と、コードの全体は、関連記事「Spring Boot Kotlin｜REST APIの完成コードとJPAの注意点」で扱っています。Spring Boot 4 で変わった依存の名前は、関連記事「Spring Boot starter一覧｜用途別の選び方とBoot 4の新旧対応表」で扱っています。

settings.gradle.kts 全文（マルチプロジェクト）

app と lib の2つのサブプロジェクトを持つ構成を作り、gradle :app:run で lib のクラスを呼べることを確かめました。

// settings.gradle.kts
pluginManagement {
    repositories {
        gradlePluginPortal()
        mavenCentral()
    }
}

dependencyResolutionManagement {
    repositoriesMode = RepositoriesMode.FAIL_ON_PROJECT_REPOS
    repositories {
        mavenCentral()
    }
}

rootProject.name = "shop"
include("app", "lib")

// lib/build.gradle.kts
plugins {
    `java-library`
}

// app/build.gradle.kts
plugins {
    application
}

dependencies {
    implementation(project(":lib"))
}

application {
    mainClass = "demo.app.Main"
}

$ gradle -q :app:run
Hi, Gradle

FAIL_ON_PROJECT_REPOS にしたまま app/build.gradle.kts に repositories { mavenCentral() } を足すと、次のエラーで止まりました。

Build was configured to prefer settings repositories over project repositories but repository 'MavenRepo' was added by build file 'app/build.gradle.kts'

libs.versions.toml の場所や名前を変えるときは、settings.gradle.kts で指定します（ドキュメントの例。from は1回・1ファイルだけ）。

dependencyResolutionManagement {
    versionCatalogs {
        create("libs") {
            from(files("../gradle/libs.versions.toml"))
        }
    }
}

よくあるエラーと原因（Gradle 8.14.3 で再現）

上の Kotlin 版のファイルを1か所ずつ Groovy 風に崩して、gradle help を実行しました。

Unresolved reference は「その名前が型の上で見つからない」という意味です。 原因は大きく3つに分かれます。

1. プラグインが plugins { } で入っていない（implementation・java・application・tasks.jar など）
2. 型が分からない形で取り出した（tasks.named("run")・ext.x）
3. 綴り違い（libs.〜 の別名）

表の上から10行は、スクリプトのコンパイルで止まるエラーです（Script compilation error の後に出ます）。最後の2行は、スクリプトの実行中に止まるエラーで、A problem occurred configuring root project の後に出ます。

エラーにならずに無視された書き方

group "com.example"（= 無し）は、Gradle 8.14.3 ではエラーになりませんでした。 ところが gradle properties で見ると group: は空のままでした。次の行に println("after group: [" + group + "]") を入れても after group: [] と出ました。代入のつもりが何もしていない、気づきにくい誤りです。書き換えたら gradle properties で group・version を確かめると見つけられます。

IDE だけで赤くなるとき

コマンドラインのビルドは通るのに、IDE だけ Unresolved reference になることがあります。Gradle のドキュメントでは、./gradlew tasks を実行して IDE だけの問題かを切り分け、IDE の再起動とキャッシュの削除を試すよう案内されています。型付きのアクセサは Gradle のプロジェクト読み込み（同期）で作られるため、libs.versions.toml を変えた後は同期し直します。

Gradle 9 で変わったこと

Gradle 9 系を動かすには Java 17〜27 が要ります（互換表の記載）。Gradle のドキュメントでは、Kotlin の互換性を壊す更新は Gradle のメジャー版のときだけ行うとされています。8 から 9 へ上げるときは、スクリプトのコンパイルエラーが新しく出ないかを確かめます。

よくある質問

Q. Groovy の build.gradle から一気に書き換える必要がありますか。 A. Groovy と Kotlin のスクリプトは同じビルドに混ぜられるので、settings.gradle.kts から1ファイルずつ書き換えられます。書き換えたら gradle help（スクリプトのコンパイル）と gradle properties で確かめると、誤りに早く気づけます。

Q. kotlin("jvm") と id("org.jetbrains.kotlin.jvm") の違いは？ A. 同じプラグインです。kotlin("jvm") は org.jetbrains.kotlin.jvm を短く書くための Kotlin DSL の関数です。Version Catalog を使うなら alias(libs.plugins.kotlin.jvm) と書きます。

Q. plugins ブロックの version に変数を使えますか。 A. kotlinlang.org では「version はこのブロックの中で文字列リテラルにする」とされています。版を一か所にまとめたいときは、Version Catalog の [plugins] と alias(…) を使います。

Q. ext と gradle.properties と Version Catalog はどう使い分けますか。 A. 依存とプラグインの版は Version Catalog、ビルドの切り替えに使う値（org.gradle.jvmargs やフラグ）は gradle.properties、ビルドの中だけで使う値は by extra が目安です。

Groovy DSL の書き方と依存の種類（api・compileOnly など）は、関連記事「build.gradle書き方｜Groovy/Kotlin DSL対訳と依存設定一覧」で扱っています。

まとめ

• Kotlin DSL は 文字列はダブルクォート、代入は =、関数は ( )
• プラグインは plugins { } で入れる。apply() だと application { } などが Unresolved reference になった
• 既存タスクは tasks.named<型>("名前") か tasks.jar・tasks.test。型を書かないと固有の関数が使えない
• ext は by extra / extra[…]。タスクの中では project.extra[…]
• 版は gradle/libs.versions.toml にまとめる。ハイフンはドットになり、libs.junit.jupiter で参照できた
• group "x"（= 無し）は Gradle 8.14.3 でエラーにならず 何もしなかった。gradle properties で確かめる

参考・出典

確認日はいずれも 2026年10月12日です。

• Gradle User Manual「Migrating build logic from Groovy to Kotlin」：https://docs.gradle.org/current/userguide/migrating_from_groovy_to_kotlin_dsl.html
• Gradle User Manual「Gradle Kotlin DSL Primer」：https://docs.gradle.org/current/userguide/kotlin_dsl.html
• Gradle User Manual「Version Catalogs」：https://docs.gradle.org/current/userguide/version_catalogs.html
• Gradle User Manual「Compatibility Matrix」：https://docs.gradle.org/current/userguide/compatibility.html
• Gradle リリース一覧：https://gradle.org/releases/
• Kotlin ドキュメント「Configure a Gradle project」：https://kotlinlang.org/docs/gradle-configure-project.html
• Spring Boot Gradle Plugin「Getting Started」：https://docs.spring.io/spring-boot/gradle-plugin/getting-started.html
• Spring Boot「System Requirements」：https://docs.spring.io/spring-boot/system-requirements.html
• Android Developers「Migrate your build to version catalogs」：https://developer.android.com/build/migrate-to-catalogs

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。