Gradleコマンドの基本形とタスク実行の仕組み

Gradleコマンドの基本書式を理解する

Gradleのコマンドライン書式は「gradle [タスク名…] [–オプション名…]」というシンプルな構造です。オプションはタスク名の前後どちらに置いても動作しますが、値を持つオプションは--console=plainのように「=」で指定するのが推奨されています。複数のタスクを実行したい場合はスペース区切りで並べるだけで、gradle clean buildのようにまとめて指定できます。また、Gradleのタスク名には省略形が使えますが、意図しないタスクが実行されるリスクがあるため、慣れないうちは完全な名前で指定するのが安全です。（出典：Gradle公式「Command-Line Interface Reference」）

タスク実行の仕組みと結果の見方

GradleではTask（タスク）が処理の基本単位です。Javaプロジェクトではコンパイル、テスト、JAR作成などがそれぞれタスクとして定義されています。コマンド実行後、Gradleはタスクが「最新かどうか」を判断し、変更がないタスクはUP-TO-DATEと表示してスキップします。

実行結果のログは-q（エラーのみ）、-i（情報レベル）、-d（デバッグ）などのオプションで切り替えられます。また、-m（–dry-run）を使えば、実際にはビルドせずに実行予定のタスク一覧だけを確認できます。

タスクの強制実行と除外指定

Gradleは一度成功したタスクを自動的にスキップしますが、--rerun-tasksオプションを使うと全タスクの最新チェックを無視して強制実行できます。ただし、これはcleanタスクとは異なり、buildディレクトリは削除しません。特定のタスクだけを除外したい場合は-x（–exclude-task）を使います。たとえばgradle build -x testと指定すると、ビルドからテストだけを除外して実行できます。また、--continueを使えば、タスクが失敗してもビルドを継続し、他の問題もまとめて確認できます。

要点：Gradleコマンドはタスク名とオプションを組み合わせて実行し、タスクは自動的にスキップされるため、必要に応じて–rerun-tasksや-xオプションで制御する。

Gradleコマンドのオプション一覧と実行環境の指定方法

実行環境を指定する主要オプション

Gradleは実行環境を柔軟に切り替えられるオプションを備えています。-g（–gradle-user-home）はGradleユーザーホームを指定し、デフォルトの~/.gradle以外の場所にキャッシュや設定を保存したい場合に使います。-p（–project-dir）はビルドを実行するプロジェクトディレクトリを指定し、カレントディレクトリ以外のプロジェクトをビルドする際に便利です。また、-P（–project-prop）でプロジェクトプロパティを、-D（–system-prop）でJVMシステムプロパティを設定できます。

ログ出力とデバッグ関連のオプション

Gradleの出力形式は--consoleオプションで制御します。plainは色なしの平文、richは色付きの詳細表示、verboseはさらに詳しい情報を表示します。CI環境ではplainが自動的に選ばれます。エラー発生時には-s（–stacktrace）でユーザー例外のスタックトレースを、-S（–full-stacktrace）で完全な詳細スタックトレースを確認できます。警告の表示方法は--warning-modeで制御し、デフォルトはsummary（要約表示）です。

ネットワークと実行制御のオプション

ネットワーク接続を制御するオプションとして、--offlineはネットワークにアクセスせず、キャッシュ済みの依存関係だけでビルドを実行します。ただし初回の依存関係解決はオフラインでは行えません。-U（–refresh-dependencies）は依存関係の状態をリフレッシュします。継続ビルドを行う-t（–continuous）は、ファイルの変更を検知して自動的にタスクを再実行するため、開発中のテスト実行などに便利です。なお、Gradle 9.6で新設された--non-interactiveは、CI環境で対話型プロンプトをすべて無効化します。

Gradle Wrapperの更新手順とセキュリティ設定

Wrapper更新の基本コマンド

Gradle Wrapperの更新は./gradlew wrapper --gradle-version=9.6.1というコマンドが公式手順です。このコマンドを実行すると、gradle-wrapper.propertiesのdistributionUrlが更新され、gradlew、gradlew.bat、gradle-wrapper.jarが再生成されます。

手動でgradle-wrapper.propertiesを編集するより、このwrapperタスクの実行が推奨されています。更新後は./gradlew --versionでバージョンを確認しましょう。（出典：Gradle 9.6.0 Release Notes）

Wrapperの配布タイプと追加オプション

Wrapperタスクには--distribution-typeオプションで配布物の種類を指定できます。binは実行バイナリのみで軽量、allはソースコードやドキュメントを含みます。通常の開発ではbinで十分ですが、IDEでGradleのソースを参照したい場合はallが便利です。また、--gradle-distribution-urlで特定のURLを直接指定したり、--gradle-distribution-sha256-sumでチェックサムを指定することも可能です。配布物はユーザーホームのwrapper/distsにキャッシュされ、同一バージョンの再ダウンロードは発生しません。

Wrapperのセキュリティ設定

Gradle Wrapperにはサプライチェーン攻撃を防ぐためのセキュリティ設定があります。distributionSha256Sumプロパティをgradle-wrapper.propertiesに設定すると、ダウンロードしたGradle配布物のSHA-256ハッシュを検証し、改ざんや破損を検出できます。公式チェックサムはgradle.org/release-checksumsで確認できます。また、networkTimeout（デフォルト10秒）でタイムアウトを設定し、validateDistributionUrl（デフォルトtrue）で想定外のURLを拒否することも可能です。（出典：Gradle公式「Best Practices for Security」）

要点：Wrapper更新は./gradlew wrapper –gradle-version=コマンドで行い、distributionSha256Sumを設定して改ざんリスクを防ぐ。

Gradleのビルドを高速化するオプションとgradle.properties設定

ビルドキャッシュと設定キャッシュの有効化

Gradleの高速化で最も効果が大きいのがビルドキャッシュと設定キャッシュです。ビルドキャッシュは--build-cacheまたはorg.gradle.caching=trueで有効化し、過去のビルド結果を再利用します。設定キャッシュは--configuration-cacheまたはorg.gradle.configuration-cache=trueで有効化し、設定フェーズの結果をキャッシュしてビルド開始を高速化します。

どちらもデフォルトではオフのため、明示的に有効化する必要があります。設定キャッシュに互換性がないプラグインがある場合は--configuration-cache-problems=warnで警告のみに変更できます。（出典：Gradle公式「Command-Line Interface Reference」）

並列実行とDaemonの活用

Gradleは--parallelオプションまたはorg.gradle.parallel=trueでマルチプロジェクトを並列実行できます。ただし、依存関係が密結合なプロジェクトでは問題が発生する可能性があるため、分離されたプロジェクトで使うべきとされています。Gradle Daemonはデフォルトで有効で、ビルドごとのJVM起動コストを削減します。Daemonの状態は--statusで確認でき、--stopで停止できます。アイドルタイムアウトはデフォルトで3時間（10800000ミリ秒）です。

gradle.propertiesでの恒久的な設定

コマンドラインで毎回オプションを指定する手間を省くには、gradle.propertiesに設定を記述します。主要な設定は以下のとおりです。

設定項目 効果 デフォルト
org.gradle.caching=true ビルドキャッシュを有効化 オフ
org.gradle.configuration-cache=true 設定キャッシュを有効化 オフ
org.gradle.parallel=true マルチプロジェクト並列実行 オフ
org.gradle.workers.max=4 最大ワーカー数を指定 CPUコア数
org.gradle.jvmargs=-Xmx4g DaemonのJVMメモリを指定 環境依存

設定の優先度は「コマンドライン引数 > プロジェクトのgradle.properties > ユーザーホームのgradle.properties」の順です。コマンドライン指定が最優先されます。

要点：高速化にはビルドキャッシュと設定キャッシュの有効化が効果的。gradle.propertiesに記述すれば毎回のオプション指定が不要になる。

Gradle 9.6系の新機能と移行時の注意点

Gradle 9.6の主要な新機能

Gradle 9.6.0では--non-interactiveオプションが新設されました。CIパイプラインやスクリプトなどの自動化環境で、対話型コンソールプロンプトをすべて無効化します。また、NO_COLOR環境変数のサポートにより、色付き出力を恒久的に抑制できるようになりました。設定キャッシュのヒット率も改善され、システムプロパティや環境変数経由のプロジェクトプロパティを正確に追跡することで、より多くの場面でキャッシュが再利用されます。（出典：Gradle 9.6.0 Release Notes）

Groovy DSLの非推奨変更に注意

Gradle 9.6ではGroovy DSLにおける「親プロジェクトからの暗黙的なプロパティ・メソッド参照」が非推奨になりました。子プロジェクトのビルドスクリプトがローカルで未定義のプロパティやメソッドを参照し、それが親プロジェクトに解決される挙動は、Gradle 10で削除される予定です。移行を早めに進めたい場合は、NO_IMPLICIT_LOOKUP_IN_PARENT_PROJECTSフィーチャープレビューを有効にすると、Gradle 10の挙動を先行して試せます。

9.6.1へのアップグレードとJava互換性

Gradle 9.6.1は9.6.0の最初のパッチリリースで、2026年6月26日に公開され、公式は9.6.1へのアップグレードを推奨しています。Gradle 9.6系を実行するにはJDK 17以上が必要で、Java 26までサポートされています。Java 26でGradle自体を実行するにはGradle 9.4.0以降が必要です。

移行時の注意点として、古い記事にある「JDK 8で実行できる」という説明は現行版には適用できません。Gradleを実行するJDKとコンパイル対象のJavaバージョンは別物で、Java Toolchainsを使えば分離して管理できます。（出典：Gradle 9.6.1 Release Notes）

要点：9.6系では–non-interactiveの追加とGroovy DSLの暗黙参照非推奨化に注意。JDK 17以上で実行可能、Java 26はGradle 9.4.0以降で対応。