概要: GradleはJavaプロジェクトのビルドを自動化するオープンソースツールです。本記事では、初心者向けにGradleの基本的な使い方からインストール方法、プロジェクト作成手順、主要コマンド、よくあるエラーへの対処法までを解説します。
Gradleとは何か：ビルド自動化ツールの役割とできること
ビルド自動化ツールとしてのGradleの基本
Gradleは、JavaなどのJVMプロジェクトにおけるビルド処理を自動化するオープンソースのツールです。ソースコードのコンパイル、テスト実行、外部ライブラリの取得、依存関係の解決、JARなどのパッケージング、成果物の公開まで、開発に必要な一連の作業をまとめて実行できます。Gradle自体はコンパイラではなく、必要な処理をタスクとして構成・実行する役割を担います。
ビルド設定はGroovy DSLまたはKotlin DSLで記述し、従来のXML形式と比べて柔軟にカスタマイズできます。MavenもJavaで広く使われるビルドツールですが、Gradleはより柔軟な記述が可能である点が特徴です。
Gradleの主要概念：Project、Task、Plugin
Gradleを理解するうえで重要な概念はProject（プロジェクト）、Task（タスク）、Plugin（プラグイン）の3つです。Projectはビルド対象の単位で、1つのアプリケーションやライブラリを指します。Taskはコンパイルやテストなどの具体的な処理単位です。PluginはJava Pluginのように、コンパイルやテストなどのタスク群をまとめて提供する拡張機能です。
JavaプロジェクトではJava Pluginを適用することで、コンパイル、テスト、JAR作成などのタスクが自動的に利用可能になります。例えば「build」タスクを実行すると、コンパイルからテスト、パッケージングまでが一括で処理されます。
GradleとMavenの違いと選択の考え方
| 比較項目 | Gradle | Maven |
|---|---|---|
| ビルド設定の記述方法 | GroovyまたはKotlin DSL（build.gradle / build.gradle.kts） | XML（pom.xml） |
| 柔軟性 | 高い。スクリプトによるカスタマイズが容易 | 規約重視。カスタマイズはプラグイン開発が必要な場合も |
| ビルド速度 | 増分ビルド、ビルドキャッシュ、並列実行などの高速化機能あり | プロジェクト構成によってはGradleより遅い場合がある |
| 学習コスト | DSLの理解が必要 | XML構造の理解が必要 |
「Gradleが必ずMavenより高速」とは断定できません。実際のビルド時間はプロジェクト構成や設定によって変わります。GradleはMavenからの移行機能も公式に提供しており、既存のMavenプロジェクトを段階的に移行することも可能です。
Gradleのインストール方法とGradle Wrapperの基礎知識
Gradle本体のインストール方法
Gradle Wrapperを使う場合でも、Wrapper自体を最初に生成するにはGradle本体が必要です。macOSやLinuxではSDKMAN!を使うのが簡単で、sdk install gradleで最新版を導入できます。Windowsでは公式サイトからzipをダウンロードし、パスに日本語や空白を含まない場所（例：C:\gradle）に解凍して、binフォルダをシステムPATHに追加します。
インストール後はgradle -vまたはgradle --versionで、GradleのバージョンやJVM情報、OSを確認できます。現行のGradleを実行するにはJDK 17以上が必要です。
Gradle Wrapperとは何か
Gradle Wrapperは、プロジェクトごとに使用するGradleバージョンを固定し、必要に応じて自動取得する仕組みです。代表的なファイルはgradlew（Linux/macOS用）、gradlew.bat（Windows用）、gradle/wrapper/gradle-wrapper.properties、gradle/wrapper/gradle-wrapper.jarです。
Wrapperを使うことで、開発者全員が同じGradleバージョンでビルドでき、CI環境でも再現性を確保できます。システムにGradleがインストールされていなくても、Wrapperが含まれるプロジェクトなら./gradlewを実行するだけで、初回に自動でGradleバイナリをダウンロードしてビルドを実行できます。
Wrapperの生成とバージョン管理
Wrapperを生成するには、システムにインストールしたGradleでgradle wrapperコマンドを実行します。これによりgradlewやgradle-wrapper.propertiesなどが生成されます。バージョンを指定する場合はgradle wrapper --gradle-version 9.6.1のように実行します。
生成されたWrapperファイルはGitなどのバージョン管理にコミットするのが基本です。これにより、プロジェクトをクローンした他の開発者やCI環境でも同じGradleバージョンでビルドできます。アップグレードは./gradlew wrapper --gradle-version 9.6.1のように、wrapperタスクを使って行うのが公式推奨です。
要点：Gradle WrapperはプロジェクトごとのGradleバージョンを固定する仕組みで、公式が推奨する標準的な実行方法です。Wrapper生成の初回のみGradle本体のインストールが必要ですが、その後は./gradlewだけでビルドできます。
Javaプロジェクトの作成手順：gradle initからビルド実行まで
gradle initによるプロジェクト初期化
Javaプロジェクトの作成にはgradle init --type java-applicationコマンドを使用します。実行すると対話形式で、実装言語（Java）、ターゲットJavaバージョン、ビルド構造、ビルドスクリプトDSL（KotlinまたはGroovy）、テストフレームワークを選択できます。
初心者の場合は、テストフレームワークにデフォルトのJUnit Jupiterを選択するのがおすすめです。対話の最後に「新しいAPI・動作を利用するか」という質問がありますが、迷ったらデフォルトのnoを選んでください。
生成されるプロジェクト構造の理解
gradle initを実行すると、以下のような構造が自動生成されます。
gradle/wrapper/：Wrapper関連ファイル（gradle-wrapper.jar、gradle-wrapper.properties）gradle/libs.versions.toml：依存関係のバージョンを一元管理するバージョンカタログgradlew/gradlew.bat：Wrapper実行スクリプトsettings.gradle.kts：プロジェクト名やサブプロジェクトの定義app/build.gradle.kts：アプリケーションのビルド設定app/src/main/java/：Javaソースコードapp/src/test/java/：テストコード
settings.gradle(.kts)にはrootProject.nameとinclude("app")が記述され、プロジェクト名の固定とサブプロジェクトの定義を行います。
最初のビルドとアプリケーション実行
プロジェクト作成後は、以下の手順でビルドと実行を行います。
- ターミナルでプロジェクトのルートディレクトリに移動します。
./gradlew build（Windowsはgradlew.bat build）を実行してコンパイル、テスト、JAR作成までを一括処理します。./gradlew runを実行してアプリケーションを起動します。
初回実行時はWrapperがGradle本体をダウンロードするため時間がかかりますが、2回目以降は高速に動作します。ビルド結果はapp/build/ディレクトリに出力され、JARファイルはapp/build/libs/に生成されます。
要点：gradle init --type java-applicationでJavaプロジェクトの雛形を自動生成し、./gradlew buildでビルド、./gradlew runでアプリケーションを実行します。生成されたWrapperやVersion Catalogはそのまま活用できます。
Gradleの主要コマンドと依存関係管理の基本
初心者が最初に覚えるべきコマンド
Gradleの主要コマンドは、ビルド、テスト、実行、タスク一覧表示の4つを押さえれば十分です。基本的には./gradlew（またはgradle）の後ろにタスク名を指定して実行します。
| コマンド | 実行内容 |
|---|---|
./gradlew build |
コンパイル、テスト、JAR作成までを一括実行 |
./gradlew test |
テストのみを実行 |
./gradlew run |
アプリケーションを実行（applicationプラグイン適用時） |
./gradlew tasks |
利用可能なタスク一覧を表示 |
./gradlew dependencies |
依存関係ツリーを表示 |
エラー調査時は--stacktraceオプションを付けると詳細なスタックトレースが表示されて原因を特定しやすくなります。Gradle Daemonの状態確認はgradle --status、停止はgradle --stopで行えます。
依存関係管理の基本：repositoriesとdependencies
Gradleの依存関係管理は、「どのリポジトリから取得するか」をrepositoriesブロック、「何を使うか」をdependenciesブロックに記述します。Javaプロジェクトでは通常、Maven Centralをリポジトリに指定します。
依存関係にはスコープ（configuration）があり、外部ライブラリを利用する場合はimplementation、テストでのみ必要な場合はtestImplementationを使うのが基本です。推移的依存関係（依存しているライブラリがさらに依存しているライブラリ）もGradleが自動で解決します。
libs.versions.toml（Version Catalog）の活用
gradle initで生成されるlibs.versions.toml（Version Catalog）を使うと、依存関係のバージョンを一元的に管理できます。Kotlin DSLの場合、dependenciesブロックでimplementation(libs.guava)のように簡潔に参照できます。
従来はbuild.gradleに直接「group:artifact:version」の形式で記述していましたが、Version Catalogを使うことでバージョン変更が1ファイルの編集で済み、複数モジュールでのバージョン統一も容易になります。依存関係の競合が起きた場合は./gradlew dependenciesや./gradlew dependencyInsight --dependency <groupId>で依存ツリーを調査できます。
要点：ビルドは./gradlew build、テストは./gradlew test、アプリ実行は./gradlew runが基本です。依存関係はrepositoriesで取得先を、dependenciesで利用ライブラリを指定し、Version Catalogでバージョンを一元管理します。
よくあるエラーと対処法：Javaバージョン互換性とトラブルシューティング
Unsupported class file major versionエラーの対処
Gradleを実行する際に最もよく遭遇するのがUnsupported class file major version 65（または61、69など）というエラーです。これは「Gradleの実行環境として使用しているJDKバージョンが、Gradleバージョンに対応していない」ことが原因です。クラスファイルのmajor versionはJavaバージョンと対応しており、例えば65はJava 21、61はJava 17を表します。
対処法は、Gradleをアップグレードして対応バージョンにするか、実行環境のJDKをダウングレードするかのどちらかです。GradleとJavaの互換性は公式のCompatibility Matrixで確認できます。
プロジェクト作成・依存関係に関するエラー
「Task 'build' not found」というエラーは、カレントディレクトリにビルドファイル（build.gradle / build.gradle.kts）が存在しないことが原因です。ファイル名の大文字小文字を区別する環境（Linuxなど）では、Build.gradleのように大文字で作成すると認識されません。正しい場所に正しいファイル名でビルドファイルを配置してください。
「Could not resolve all files for configuration ':compileClasspath'」は、依存関係の座標（groupId:artifactId:version）の記述ミスやリポジトリへの接続問題が原因です。./gradlew dependenciesで依存関係の解決状況を確認し、記述ミスやバージョン指定の誤りを修正します。
Gradle Daemonとビルド速度の問題
Gradle DaemonはGradle 3.0以降デフォルトで有効なバックグラウンドプロセスで、ビルド間のJVM起動待ちを省略して高速化します。デーモンはアイドル状態が3時間続くと自動停止し、システムメモリが少ない場合も停止します。ビルドが遅い、またはデーモンが頻繁に再起動する場合は、gradle.propertiesにorg.gradle.jvmargs=-Xmx2048mのように記述してヒープサイズを増やすことを検討します。
デーモンの状態確認はgradle --status、手動停止はgradle --stopで行えます。CI環境では--no-daemonオプションを使ってデーモンを無効化するのが一般的です。初回ビルド時にGradleが自動ダウンロードされる現象は正常な動作で、Wrapperが指定バージョンのGradleをキャッシュしているだけです。
要点：エラーの多くは「JavaバージョンとGradleバージョンの互換性」と「ビルドファイルの配置」が原因です。エラー発生時は--stacktraceオプションで詳細を確認し、公式互換性表でJavaとGradleの対応をチェックしてください。
まとめ
よくある質問
Q: Gradleとは何ですか？
A: Gradleは、JavaなどのJVMプロジェクトで利用できるビルド自動化ツールです。ソースコードのコンパイル、テスト実行、外部ライブラリの取得、依存関係の解決、JARなどへのパッケージングなどを自動化できます。オープンソースであり、GroovyまたはKotlinを使ったDSLでビルド設定を柔軟に記述できる点が特徴です。
Q: Gradleをインストールするにはどうすればいいですか？
A: Gradleのインストール方法はOSによって異なります。macOSやLinuxではSDKMAN!が推奨され、Windowsでは公式サイトからZIPファイルをダウンロードして展開し、PATHを通す方法が一般的です。ただし、Gradle Wrapperが含まれる既存プロジェクトでは、Gradle本体をインストールしなくてもWrapperが自動でGradleをダウンロードして実行できます。
Q: Gradle Wrapperとは何ですか？
A: Gradle Wrapperは、プロジェクトで使用するGradleバージョンを固定し、必要に応じてそのバージョンのGradleを自動的に取得・実行する仕組みです。gradlew（Linux/macOS用）やgradlew.bat（Windows用）といったスクリプトと、gradle/wrapperディレクトリ内のファイルで構成されます。Wrapperを利用することで、開発者全員が同じGradleバージョンを使用でき、CI環境でも一貫したビルドが可能になります。
Q: JavaプロジェクトでGradleを使い始めるにはどうすればいいですか？
A: Gradleをインストールした後、プロジェクトのルートディレクトリで『gradle init –type java-application』を実行します。対話形式で言語（Java）、DSL（Kotlin or Groovy）、ターゲットJavaバージョン、テストフレームワーク（JUnit Jupiterなど）を選択すると、必要なビルドファイルやソースコード、Gradle Wrapperが自動生成されます。その後、『./gradlew build』でビルドを実行できます。
Q: 『Unsupported class file major version』エラーが発生するのはなぜですか？
A: このエラーは、使用しているGradleのバージョンが、実行環境のJDK（Java）バージョンに対応していない場合に発生します。例えば、Java 21（major version 65）でGradle 8.3以前を使用すると発生します。対処法は、Gradleを互換性のあるバージョンにアップグレードするか、Gradleの実行に適したJDKバージョンにダウングレードすることです。Gradle公式の互換性表で、JavaバージョンとGradleバージョンの対応を確認してください。
