build.gradle.kts とは何か？なぜ今 Kotlin DSL なのか

Gradle のビルドスクリプトには長らく Groovy DSL（build.gradle）が使われてきましたが、現在は Kotlin DSL（build.gradle.kts） が公式の標準となっています。Android Studio Giraffe 以降では新規プロジェクトのデフォルトが Kotlin DSL に切り替わり、JetBrains も Kotlin Blog で「Kotlin DSL is Now the Default for New Gradle Builds」と正式に発表しました。

この記事を読むことで、次のことができるようになります。

• build.gradle.kts の基本構文を理解し、自分で書けるようになる
• Groovy DSL からスムーズに移行できる
• バージョンカタログ（libs.versions.toml）を活用した依存関係管理ができる
• よくあるエラーを自力で解決できる

Groovy DSL との違い：なぜ移行すべきか

Groovy は動的型付け言語であり、IDE のコード補完や型チェックが効きにくいという欠点がありました。一方、Kotlin は静的型付け言語のため、ビルドスクリプトのエラーをコンパイル時に検出できます。主な違いをまとめると以下のとおりです。

• コード補完とナビゲーション：IntelliJ IDEA / Android Studio でフル活用できる
• 型安全性：タイポや型ミスをエディタ上で即座に検出できる
• リファクタリング：変数名や関数名を安全に一括変換できる
• ビルドパフォーマンス：スクリプトがコンパイルされるためインクリメンタルビルドが高速化する

Groovy DSL と Kotlin DSL は同一プロジェクト内で共存できるため、一度にすべてを移行する必要はありません。ファイル単位で段階的に移行できます。

構文の主な違い一覧

以下に Groovy DSL と Kotlin DSL の代表的な構文差異を示します。

• 変数宣言：def foo = "bar" → val foo = "bar"
• 関数呼び出し：括弧省略不可（apply plugin: 'java' → apply(plugin = "java")）
• プロパティ代入：= が必須（versionCode 1 → versionCode = 1）
• 文字列：シングルクォートは使えない（すべてダブルクォート）
• Boolean プロパティ：minifyEnabled → isMinifyEnabled（is プレフィックスが必要な場合あり）

基本的な書き方

プロジェクトレベルの build.gradle.kts

ルートプロジェクトの build.gradle.kts では、主にプラグインのバージョン宣言を行います。モジュールへの適用は行わず、apply false を指定するのが一般的なパターンです。

// build.gradle.kts（ルート）
plugins {
    alias(libs.plugins.android.application) apply false
    alias(libs.plugins.android.library) apply false
    alias(libs.plugins.kotlin.android) apply false
}

モジュールレベルの build.gradle.kts（Android アプリ）

アプリモジュールの build.gradle.kts は次のような構成になります。

// app/build.gradle.kts
plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.android)
}

android {
    namespace = "com.example.myapp"
    compileSdk = 35

    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 24
        targetSdk = 35
        versionCode = 1
        versionName = "1.0"
    }

    buildTypes {
        release {
            isMinifyEnabled = true
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro"
            )
        }
        debug {
            isDebuggable = true
        }
    }

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }

    kotlinOptions {
        jvmTarget = "17"
    }
}

dependencies {
    implementation(libs.androidx.core.ktx)
    implementation(libs.androidx.appcompat)
    implementation(libs.material)
    testImplementation(libs.junit)
    androidTestImplementation(libs.androidx.junit)
}

バージョンカタログ（libs.versions.toml）の活用

Gradle 7.4 以降で正式導入されたバージョンカタログは、依存関係のバージョンを一元管理する仕組みです。gradle/libs.versions.toml ファイルに定義し、すべてのモジュールから参照できます。

# gradle/libs.versions.toml
[versions]
agp = "8.7.0"
kotlin = "2.0.0"
coreKtx = "1.13.1"
appcompat = "1.7.0"
material = "1.12.0"
junit = "4.13.2"
androidxJunit = "1.2.1"

[libraries]
androidx-core-ktx = { group = "androidx.core", name = "core-ktx", version.ref = "coreKtx" }
androidx-appcompat = { group = "androidx.appcompat", name = "appcompat", version.ref = "appcompat" }
material = { group = "com.google.android.material", name = "material", version.ref = "material" }
junit = { group = "junit", name = "junit", version.ref = "junit" }
androidx-junit = { group = "androidx.test.ext", name = "junit", version.ref = "androidxJunit" }

[plugins]
android-application = { id = "com.android.application", version.ref = "agp" }
android-library = { id = "com.android.library", version.ref = "agp" }
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }

libs.versions.toml を使うことで、バージョン番号が一か所にまとまり、複数モジュール間でのバージョン不整合を防げます。また、IDE 上で libs. と入力するだけでコード補完が効くため、タイポによるエラーも激減します。

JVM ライブラリプロジェクトの build.gradle.kts

Android に依存しない純粋な JVM ライブラリでは、kotlin("jvm") プラグインを使います。

// lib/build.gradle.kts
plugins {
    kotlin("jvm") version "2.0.0"
}

kotlin {
    jvmToolchain(17)
}

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

よくあるつまずきポイントと解決策

1. plugins ブロックで alias が認識されない

症状： alias(libs.plugins.xxx) に赤線が引かれ、「Unresolved reference: libs」と表示される。

原因・解決策： Gradle 8.1 未満では plugins {} ブロック内でバージョンカタログの参照がサポートされておらず、アノテーションが必要でした。Gradle 8.1 以降にアップグレードするのが最もシンプルな解決策です。また、gradle/wrapper/gradle-wrapper.properties の distributionUrl が古い場合も同様のエラーが起きます。

# gradle/wrapper/gradle-wrapper.properties
distributionUrl=https\://services.gradle.org/distributions/gradle-8.9-bin.zip

2. Boolean プロパティで型エラーが出る

症状： minifyEnabled true と書いたらエラーになる。

解決策： Kotlin DSL では is プレフィックスが必要なプロパティがあります。= 演算子も省略できません。

// NG（Groovy 記法）
minifyEnabled true
debuggable true

// OK（Kotlin DSL）
isMinifyEnabled = true
isDebuggable = true

3. 文字列でシングルクォートを使っている

症状： applicationId 'com.example.app' と書いたらコンパイルエラー。

解決策： Kotlin ではすべての文字列はダブルクォートです。また、プロパティ代入には = が必要です。

// NG
applicationId 'com.example.app'

// OK
applicationId = "com.example.app"

4. IDE でコード補完が効かない

症状： libs. と入力してもサジェストが出ない。

解決策： Gradle プロジェクトを再同期（Sync）してください。Android Studio の場合は「File → Sync Project with Gradle Files」を実行します。また、IDE が「Gradle モデルからインポート」されていない場合は、.gradle ディレクトリを削除して再ビルドすることで解消できるケースがあります。

5. buildSrc での共通設定がうまく読み込めない

マルチモジュールプロジェクトで共通ビルドロジックを buildSrc に切り出した場合、buildSrc/build.gradle.kts 自体も Kotlin DSL で記述できます。kotlin-dsl プラグインを適用するだけで有効になります。

// buildSrc/build.gradle.kts
plugins {
    `kotlin-dsl`
}

repositories {
    google()
    mavenCentral()
}

まとめと次のステップ

build.gradle.kts（Kotlin DSL）を使うことで、型安全なビルドスクリプト・強力な IDE サポート・バージョンカタログによる一元管理という三つの大きなメリットを得られます。Groovy DSL からの移行は段階的に行えるため、まずは規模の小さいモジュールの build.gradle を build.gradle.kts にリネームし、構文を修正することから始めるのがおすすめです。

次のステップとして、以下のトピックも合わせて学ぶと理解がさらに深まります。

• Convention Plugins：buildSrc や included build を使った共通ロジックのモジュール化
• Gradle Build Cache：ビルドキャッシュを活用した CI/CD の高速化
• Gradle Configuration Cache：設定フェーズのキャッシュで繰り返しビルドを高速化
• 公式ドキュメント：docs.gradle.org の「Kotlin DSL Primer」は必読です

まずは手元の build.gradle を一つ選んで build.gradle.kts にリネームし、IDE のエラー表示に従って修正してみましょう。最初の一歩を踏み出せば、Kotlin DSL の快適さをすぐに実感できるはずです。