日々常々

ふつうのプログラマがあたりまえにしたいこと。

GradleWrapperの追加や更新の手順

Gradle
  • Gradle 7.3.2

Gradleを使っているプロダクトだと、基本的にGradleWrapperを使うと思います。 プロジェクト作成時に最新のGradleを使うかと思いますが、Gradleの更新でたまにビルド時間短縮とかもあるんで、新機能使わなくてもWrapperも更新していきたいところです。

なお 公式のユーザーガイド に書かれている内容です。

short answer

私がやってるのは、追加も更新も「 gradle wrapper を叩く」だけです。

以下は説明。

前提

SDKMAN! でGradleをインストールしています。

sdk install gradle

なお、手元のGradleのバージョンアップも一緒です。install で新しいのがあったらインストールしてくれる。

sdk install gradle

普通は sdk upgrade gradle なんだろうけど、upgradeを忘れたり「updateとどっちだっけ？」とかなるので、雑にinstallしてたりします。覚えるコマンドが少ないのはいい・・・

windows環境でどうするかは知らない。

なるほど。

GradleWrapperがあたりまえなので手元にGradleをインストールすることも少ないかもしれません。 私は一からプロジェクトを作ることも多いので入れてます。

GradleWrapperの追加

gradle wrapper

GradleWrapperがないGradleプロジェクトではこれで追加。build.gradle に wrapper タスクを書いておく必要とかはないです。（昔は要ったんだっけ。忘れた。）

……なんだけど、だいたいプロジェクト作成時に入ってたりする。 すくなくとも Spring InitializrでGradle選んだり、gradle init で作るとGradleWrapperは勝手についてきます。 なので、追加のためにgradle wrapper 叩くことは案外なかったりする。

æ›´æ–°

本題。一番やる頻度は高いんだろうけど、「どうするんだっけ？」ってなるやつです。

先頭で書いたように 公式のユーザーガイドにUpgrading the Gradle Wrapperと言うズバリな項目 があるんですが、この項目に Example: Upgrading the Wrapper version の見出しでこう言うの書いてるんですよね。

$ ./gradlew wrapper --gradle-version 7.3.2

BUILD SUCCESSFUL in 4s
1 actionable task: 1 executed

これが罠。「Example」であって「これ一発で更新できるよ！」って言うものじゃないんです。前段の説明に書いてるんだけど、英語読まずに コマンドだけ実行しちゃう人が結構多いので、このブログ書いてます。

私が推奨する方法は「追加と同じことをしよう」です。すなわち実行するコマンドは以下になります。

gradle wrapper

……最新のGradleが手元にあるならば。

「gradle-wrapper.properties の distributionUrl を書き換える」や「 gradlewで--gradle-versionを指定してwrapperタスクを実行する」は、この方法を取れないときの次善策です。

動作はしますが、これらの手順の後は ./gradlew wrapper （バージョン指定なしでよい） を実行しましょう。 なんだか面倒臭いですが、wrapper タスクでの gradlew や gradlew.bat、gradle-wrapper.jar の更新は、実行したGradleのバージョンでなされます。なので--gradle-versionを指定しても置き替わらないんですよね。

更新手順まとめ

手元にGradleがある場合は、手元のGradleを最新にして gradle wrapper を叩けばOKです。

手元にGradleがない場合は以下のいずれかになります。

  • ./gradlew wrapper --gradle-version {目的のバージョン} を叩いて、 ./gradlew wrapper を叩く。
  • --gradle-version と言うオプションを忘れてたら gradle-wrapper.properties のURLを書き換えて、 ./gradlew wrapper を叩く。

どの手順でも「wrapper タスクを新しいGradleで叩く」は変わりありません。

更新したのをコミットするときに gradlew, gradlew.bat が更新されてなかったら、「更新できてないんじゃ？」と疑ってみるのがいいと思います。バージョンアップのたびになんか変わってますので。（今後変わらないことあるかもだけど）

追記: 2025-03-26

本日リリースされたGradle8.13のリリースノートでは以下のように記述されています。

./gradlew wrapper --gradle-version=8.13 && ./gradlew wrapper

上の方に書いてある「もう一回実行しましょう」なのを公式のコマンドで示してくれるようになりました。 今後はリリースノートの手順で大丈夫です。