日々常々

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

GradleWrapperの追加や更新の手順

  • 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.gradlewrapper タスクを書いておく必要とかはないです。(昔は要ったんだっけ。忘れた。)

……なんだけど、だいたいプロジェクト作成時に入ってたりする。 すくなくとも 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.propertiesdistributionUrl を書き換える」や「 gradlew--gradle-versionを指定してwrapperタスクを実行する」は、この方法を取れないときの次善策です。

動作はしますが、これらの手順の後は ./gradlew wrapper (バージョン指定なしでよい) を実行しましょう。 なんだか面倒臭いですが、wrapper タスクでの gradlewgradlew.batgradle-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 が更新されてなかったら、「更新できてないんじゃ?」と疑ってみるのがいいと思います。バージョンアップのたびになんか変わってますので。(今後変わらないことあるかもだけど)

Javaで「ライブラリの最新版がある」と言うときの基礎知識

Log4j 2のバージョンアップのやりかた で "「Mavenリポジトリ」の指すもの" を軽く書きましたが、いい機会なのでもう少し書いておきます。

最新版は使える?

f:id:irof:20211214123532p:plain

https://twitter.com/irof/status/1469139048954724354

こういうツイートをしまして。 見てる順番は Log4j 2のトップページMvnRepositoryのlog4j-coreGitHubのLog4j 2のタグ一覧Central Repositoryのlog4j-apiディレクトリです。

ツイートの状態から「Log4j 2はリリース成功してからタグ作るで運用してるんだなぁ」とか、リリース成功したら自動でタグ作ってるわけでもないのかなぁとか思いました。私はタグをトリガーにリリースのパイプライン動かすのが好きです。リリース失敗したら消したくなるけど。

基本的に「最新版が使える」は「公開されているMavenリポジトリから取得できる」であり、狭義では「Central Repositoryに公開されている」を指します。 ツイートの4枚目で 2.15.0 の存在を確認できているので「最新版が使える」状態でした。

現代ではMavenやGradleのようなビルドツールを使わないことは考えづらく、jarを手動でダウンロードすることはほとんどありません。 あるとしても一部のAntでのビルドを保守している文脈か、ライセンス等の問題でCentral Repositoryなどで公開できない一部のライブラリを使用する場合です。

たとえば Log4j 2サイトのダウンロードページから最新版のjarがダウンロードできたとしても、それを使用するようにビルドツールを設定してあげる必要があります。 最近ではほとんど用途のないlibディレクトリに配置してのパス指定や、後述のインハウスリポジトリへの一時的な登録などになります。これらをしなければ「自分の手元ではビルドできてもCIではビルドできない」となったりして、前時代的だし、どちらも面倒。やらずに済むならやりたくないのが今日この頃です。やらずに済んでよかった。

インデックスサイト

リポジトリの階層をたどるのは面倒なので、 https://search.maven.orghttps://mavenrepository.com のようなMavenリポジトリの検索を助けてくれるサービスを使用することが多いでしょう。Googleとかで検索してもこれらが先に出てくるはずです。

私はインデックスサイトとか呼んでますが、共通の呼び名は知りません。インデックスサイトはそれぞれのサイト次第であり、別に mvn コマンドが使用する最新のリポジトリの状態を示すものではありません。

ここになくても、使えるものは使えます。検索を助けてくれるだけ。

Mavenリポジトリ

mvn コマンドはMavenリポジトリを使用します。 Mavenリポジトリはローカルリポジトリとリモートリポジトリに分けられますが、基本的にリモートリポジトリが原本、ローカルはキャッシュくらいの感覚でOKです。

mvn install とか叩くとローカルリポジトリに登録されますが、使えるのは自分だけです。リモートリポジトリへの登録は mvn deploy とかですが、サーバーのURLとか認証情報とかが必要になってきます。

リポジトリの場所は .m2/settings.xml とか pom.xml とかコマンド実行時の引数とかで設定できますが、何も設定しなければローカルは ~/.m2/repository で、リモートリポジトリは https://repo.maven.apache.org/maven2/ です。

プロジェクトで使ってるリモートリポジトリがわからなかったら、存在しないライブラリ落とそうとしたらエラーログに出てきたりします。

f:id:irof:20211214134633p:plain

修飾なしで「Mavenリポジトリ」と言うと、基本的にはCentral Repositoryを指すと思って大丈夫です。 他はSpringのMavenリポジトリとか修飾をつけて呼ぶはずです。Central Repository以外のリポジトリを使用する動機は、そのリポジトリでしか公開されていないものを使用したい場合で、多くはSNAPSHOTやMilestoneなリリースを使いたい場合になります。他は作者が何かしらの理由によりCentral Repositoryで公開していない場合でしょう。(「めんどくさい」って理由で上げないことも多いと思います。)

ライブラリごとのリポジトリの場所

たとえばLog4j 2のリリースリポジトリhttps://repository.apache.org/service/local/staging/deploy/maven2 で、SNAPSHOTリポジトリhttps://repository.apache.org/content/repositories/snapshots のようです。 なのでSNAPSHOTはSNAPSHOTリポジトリorg/apache/logging/log4j/log4j-core にあります。

これはLog4j 2のpom.xml を読めばわかることです。 org.apache.logging.log4j:log4j-core -> org.apache.logging.log4j:log4j -> org.apache.logging:logging-parent -> org.apache:apache とparentを辿れば <distributionManagement>に書かれています。4階層もあって面倒なので、自力でpom読むよりは手元のpomでmvn help:effective-pom する方が確実ですし、結局<property>なのでビルド時に上書きできるんですけども。

と、pom.xmlを見たら書いてたりするという、あまり役に立たない知識を書いておきたかっただけです。 公式サイトのSnapshot buildsに書いてあるので、素直にこっち見た方がいいです。

インハウスリポジトリ

リモートリポジトリのうち、組織内部でのみ使用する目的で作られたリポジトリをインハウスリポジトリと言ったりします。

私が使ったことがあるのはSonatypeのNexus(Central Repositoryが使用している)や、JFrogのArtifactory(Springが使用している)。最近ではGitHub PackagesAWS CodeArtifactなども選択肢に入るかもしれません。

自分達だけが使うライブラリを登録したい場合はもちろん、クローズドなCentral Repositoryにアクセスできない環境や、Central Repositoryが落ちた時に備えるとか、ネットワーク的に近いところにキャッシュしてビルド時間を短縮したいとか、いろんな理由で使われます。

インハウスリポジトリを使用する場合、開発端末の ~/.m2/settings.xml に書くことが多いと思います。

Central Repository

Central Repsitoryは、Sonatypeが運営しており、世界中で使われ、あちこちでミラーリングされてたりするリポジトリです。

「セントラリリポジトリ」の他、「Mavenセントラルリポジトリ」とか、「セントラル」とか、先にも書きましたが単に「Mavenリポジトリ」と呼ばれたりします。いずれもCentral Repositoryのことです。JVM界隈では「ここで公開されているライブラリはだいたいどこでも使える」と言っていいです。

逆にここで公開されていないライブラリを使うには、個別の対応が必要になる認識です。

Central RepositoryのURL

Central RepotiroyのURLは https://repo1.maven.org/maven2https://repo.maven.apache.org/maven2 があり、公式で並列してアナウンスされているもの です。なのでどっちでもいい。

内容微妙に違うし(正確には「違うことがある」かな。この記事書いた時違ったけど、今みたら同じになってた。)、確かrepo1.maven.orgからrepo.maven.apache.orgに変更された経緯があった気がするんだけど、混乱したからどっちでもいいを維持することにしたんでしょうかね。Central Repotitoryを運営しているSonatypeの運営するインデックスサイト https://search.maven.org/ のリンクがrepo1向いてるんで、インターネットで示すのはrepo1がいいかなと思っています。リリースしたら両方に反映されるし。

Central Repositoryへの反映

CentralRepositoryへの反映は(個人の場合は)図のようにOpenSourceSoftwareRepositoryHostingというサービスを使用し、複数ステップで行われます。

f:id:irof:20211214205406p:plain

デプロイとリリースは別ですが、プラグインでの自動化も可能。リリース時にjavadocやsourceがあるかとか署名の検証とかが行われ、ダメだったら跳ねられます。一度リリースしたものは削除できません。分かれてるのは最終確認みたいな感じですね。

Log4j 2はApacheなのでLarge Organization向けのものになるんでしょうかね。同期にどれくらい時間がかかるかはよくわかりません。

Central Repositoryへの反映ですが、少なくともOSSRHでは図で書いているように制御不可です。数時間かかる時もあれば、さきほどは10分くらいで反映されました。この時間が問題になることは少ないですが、JIGのようにGradlePluginPortal(ほぼ即時反映)とCentral Repositoryとの同時リリースすると、「GradlePluginPortalにはあるけどCentral Repositoryにないので使えない時間」があったり、単一リポジトリのマルチモジュールでなく複数リポジトリに分かれているライブラリはCentral Repositoryに反映されてからでないとリリース作業が行えない、とかがあったりします。

Central Repositoryでのライブラリ公開は一度やっておくとこの辺りの事情がイメージしやすくなるのかなと。

Gradleの話

GradleもなんだかんだでCentral Repositoryを使います。いっとき jcenter() を使う流れはありましたが、JCenterのサービス終了に伴い、Central Repositoryに戻ってきた感じ。サービス終了が発表された時は騒ぎになりましたが、さすがにもう大丈夫でしょうか。あと3ヶ月でダウンロードもできなくなるので、そこでガン無視してたところが騒いだりしないか若干心配。

Gradleはbuild.gradleで以下のように書く必要があるので「Mavenセントラル」と言う言葉に馴染みはあるのではないでしょうか。

repositories {
    mavenCentral()
}

逆にデフォルトで使われるMavenの方がCentral Repsitoryは意識しないのかもしれないなぁ、と。

変更メモ

  • 2021-12-15T12:13
    • タイトルを 「Mavenリポジトリに最新版がある」とは から 「Mavenリポジトリに最新版がある」と言うときの基礎知識 に変えました。
  • 2021-12-15T15:50
    • さらにタイトルを Javaで「ライブラリの最新版がある」と言うときの基礎知識 に変えました。

Gradle+SpringBootでLog4j 2のバージョン更新(DependencyManagementPlugin不使用)

Log4j 2のバージョンアップのやりかた からの派生。 特化した内容なので別エントリにします。

2021-12-13追記: 今気づいたけどSpring公式ブログのLog4J2 Vulnerability and Spring Boot見るほうがシンプルでよいかもです。 本稿はバージョンダウンとか選択とかに興味あればって感じ。……./gradlew dependencyInsight --dependency {} なんてあったのね。

2021-12-20追記: 2.17.0 出てますのでコピペしてそのままにせず適宜読み替えてくださいね。

  • Gradle 7.3.1
  • SpringBoot 2.6.1

条件

DependencyManagementPlugin使ってるなら素直に設定して終了です。

準備: SpringBootでlogbackじゃなくLog4j 2を使う

spring-boot-starter-log4j2 があるので、これを入れればOK・・・ではないんですよね。 単に追加するだけだと起動できません。

SLF4J: Class path contains multiple SLF4J bindings.
...
Caused by: org.apache.logging.log4j.LoggingException: log4j-slf4j-impl cannot be present with log4j-to-slf4j
    at org.apache.logging.slf4j.Log4jLoggerFactory.validateContext(Log4jLoggerFactory.java:49)
    at org.apache.logging.slf4j.Log4jLoggerFactory.newLogger(Log4jLoggerFactory.java:39)
    at org.apache.logging.slf4j.Log4jLoggerFactory.newLogger(Log4jLoggerFactory.java:30)
...

こんなログがでます。SLF4Jが複数あるからだめーって。 ちゃんとSpringBootのリファレンスには書いてるので、その通りしましょう。

ということで、Log4j 2を使う最小セットはこうなります。

dependencies {
    implementation platform(org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES)
    implementation 'org.springframework.boot:spring-boot-starter'
    implementation 'org.springframework.boot:spring-boot-starter-log4j2'

    testImplementation 'org.springframework.boot:spring-boot-starter-test'

    modules {
        module('org.springframework.boot:spring-boot-starter-logging') {
            replacedBy 'org.springframework.boot:spring-boot-starter-log4j2'
        }
    }
}

./gradlew dependencies --configuration runtimeClasspath で一覧。

f:id:irof:20211211201658p:plain

いい感じですね。……「いい感じ」と言われてもわからないかもなので一応。期待通りConstraintされている、Log4j 2が入っている、Logbackが入っていない、あたりです。あとLog4j 2もちゃんと2.14.1です。

もちろんMavenと同じくexcludeしてもいいです。選べるならお好きなやり方で。選べるだけの知識は必要になりますが。starter1つとかならいいけど、複数ある時に全部からexcludeするの案外めんどいよ。

Log4j 2のバージョンアップ

さあバージョンを上げましょう。 SpringBootのリファレンスに書いてある通り、ですがDependencyManagementPluginを使っていないのでlog4j2.versionプロパティを使用できません。残念。

書かれてることに従ってやるなら、以下の追加です。

dependencies {
    implementation platform(org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES)
    implementation 'org.springframework.boot:spring-boot-starter'
    implementation 'org.springframework.boot:spring-boot-starter-log4j2'

    testImplementation 'org.springframework.boot:spring-boot-starter-test'

    modules {
        module('org.springframework.boot:spring-boot-starter-logging') {
            replacedBy 'org.springframework.boot:spring-boot-starter-log4j2'
        }
    }

    configurations.all {
        resolutionStrategy.eachDependency { DependencyResolveDetails details ->
            if (details.requested.group == 'org.apache.logging.log4j') {
                details.useVersion '2.15.0'
            }
        }
    }
}

./gradlew dependencies で見てもらったり、IDEの依存ライブラリでバージョン確認。

f:id:irof:20211211203122p:plain

画像はIntelliJ IDEAさん。ライブラリ一覧を軽く見たい時はコマンドとかGradleウィンドウのDependenciesとかでなく、ProjectウィンドウのExternal Librariesで見ることが多い私です。 タイプしたらハイライトしてくれるしね。

やりたいことはできた。けれど、いくつかの問題があります。

  • build.gradle はシンプルに保ちたい。できればifなんて書きたくない。
  • Log4j 2のライブラリって全部org.apache.logging.log4jでいいんだっけ?他ってなかったっけ?他がこのGroup使ったりしないっけ?(最後は杞憂だけど。)
  • configurationsresolutionStrategyなんて初めて見た←

仕切り直し。 spring-boot-dependenciesでもplatformを使ってるので、こちらもplatformでやればいいです。Log4j 2は log4j-bom があります。

強制したい時はenforcedPlatformとかもありますが、今回はバージョンアップなのでplatformでもよいです。

ということで、最終的なbuild.gradledependenciesはこうなります。

dependencies {
    implementation platform(org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES)
    implementation platform('org.apache.logging.log4j:log4j-bom:2.15.0')
    implementation 'org.springframework.boot:spring-boot-starter'
    implementation 'org.springframework.boot:spring-boot-starter-log4j2'

    testImplementation 'org.springframework.boot:spring-boot-starter-test'

    modules {
        module('org.springframework.boot:spring-boot-starter-logging') {
            replacedBy 'org.springframework.boot:spring-boot-starter-log4j2'
        }
    }
}

f:id:irof:20211211220055p:plain

オーライ。

バージョン競合時の話

Gradleのバージョン解決は非常に細やかな制御ができるのですが、何もしない場合、競合したら 新しいバージョンが優先 されます。 このため「build.gradleに明示したバージョンが必ずしも使われる訳ではない」という意味です。今回のようなのだと新しいバージョンへの上書きなので問題ないのですが、古いバージョンへの上書きは期待通り動作しません。

仮に今回 2.14.1 -> 2.15.0 ではなく 2.14.0 へのバージョンダウンとかだと、platform ではこの方法ではうまくいきません。 たとえば以下のように log4j-core2.14.0 を明示しても、spring-boot-dependencies2.14.1が使用されます。

dependencies {
    implementation platform(org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES)
    implementation 'org.apache.logging.log4j:log4j-core:2.14.0'
}

org.apache.logging.log4j:log4j-core:2.15.0 なら (log4j-corelog4j-apiは)2.15.0 が使用されます。 BOMが使えるなら先に挙げた enforcedPlatform でバージョンダウンも強制できますが、バージョンを下げるのは案外面倒ってだけ記憶の片隅に置いておくといいかなと思います。 他の解決方法もほんと色々あるのですが、ここでは割愛します。

Mavenだと<dependencyManagement>してても<dependency>で明示した方が優先されるので、注意が必要なところ。

ちゃんとした話はGradleのリファレンスを参照してください。 こちらでも書かれていますが、Mavenだと近さで選ばれます。

蛇足: SpringのDependencyManagementPluginを使わないわけ

たいそうな理由もないんですが、バージョン解決の仕組みが重なるのが嫌なんです。 「この設定Gradleだっけ、プラグインだっけ」とか、「Gradleのバージョンアップでこの辺変わったけどどう影響するんだろ」とか。

  • GradleのSpringBootPluginからDependencyManagementPluginが分離された
  • GradleにBOMサポートが入った

そこそこ長くGradleとSpringBootを使っているので、この2つのイベントをリアルタイムで見ています。 そしてGradleのバージョンもガンガン上がってる。「ついていくならGradleのほうかな」と、少なくとも依存解決の文脈ではそう思っているので、DependencyManagementPluginの使用は避けています。

別に使ってるのを無理矢理外したりはしないけどね。

あとがき

Gradleむずかしい(Mavenが簡単とは言っていない)。

BOMがあれば、BOMをplatformで使うのがいいと思います。log4j-bomspring-boot-dependenciespom.xml読んでたら見つけました。 複数のBOMを読ませたら競合バージョン解決が行われ、基本的には新しい方が使われます。Mavenの深さとどちらがいいかは好みが分かれるところ。

BOMがなければconfigurationsとかで対象ライブラリ判定して適用する感じになります。 スクリプト書けるんでそれなりに柔軟な判定は可能、でもbuild.gradleにあまり処理は書きたくない感もある。