一个从Precompiled Script Plugin访问Gradle Version Catalog的Workaround

太长不看：在 buildSrc/build.gradle.kts 中应用 gradle-buildconfig-plugin 或 BuildKonfig 插件。

1. 简介

长期以来，Gradle社区一直面临一个几乎无法解决的问题gradle/gradle#15383，这导致了极大的挫败感。问题涉及到如何从precompiled script plugin访问version catalog。虽然存在许多workaround，但今天我想向您展示我最近找到的一种workaround。

让我们开始吧。

2. 理解问题

问题gradle/gradle#15383由  Cédric Champeau (melix)提出，内容如下：

In a similar way to gradle/gradle#15382, we want to make the version catalogs accessible to precompiled script plugins. Naively, one might think that it’s easier to do because precompiled script plugins are applied to the “main” build scripts, but this isn’t necessarily the case:

• First, precompiled script plugins can be published too, meaning that they are no different from regular plugins in practice
• Second, precompiled script plugins can be declared in included builds, not just buildSrc

Therefore, the “version catalog” that a precompiled script plugin should see cannot be the catalog declared in the “main build”. It cannot be, either, the catalog declared in the project which itself declares the precompiled script plugin (typically the settings file of the buildSrc project): in particular, the catalogs declared in buildSrc/settings.gradle are for the build logic of buildSrc itself, not for the “main” build.

简而言之，precompiled script plugin无法访问version catalog，而且解决这个问题相当困难。但为什么呢？为了更好地理解这个问题，让我们回顾一下Gradle中的一些概念。

2.1. 什么是composite build？

Gradle官方文档说：

A composite build is a build that includes other builds.

翻译过来就是：

composite build是包含其他构建的构建。

基本上，这就是你在settings.gradle.kts文件中的includeBuild("relative/path/to/another/gradle/project")语句。包含的构建本身是一个有效的、独立的、自成体系的Gradle项目，它也有自己的settings.gradle.kts和/或build.gradle.kts文件。

你可以尝试在relative/path/to/another/gradle/project中添加Gradle wrapper，并在你的IDEA中打开该文件夹。然后你的IDEA就会将其视为一个普通的Gradle项目，就像你平常的Java Gradle项目😂。

2.2. precompiled script plugin作为composite build

Gradle官方文档推荐两种构建多模块项目的结构方式。要么使用buildSrc，要么使用composite build将常见的构建逻辑提取到一个构建项目中，供你的多模块项目中的子项目使用。

这是文件夹结构：

.
├── gradle/
├── gradlew
├── settings.gradle.kts
├── build-logic/ 或 buildSrc/
│   ├── settings.gradle.kts
│   └── conventions
│       ├── build.gradle.kts
│       └── src/main/kotlin/shared-build-conventions.gradle.kts
├── sub-project1/
│   └── build.gradle.kts
├── sub-project2/
│   └── build.gradle.kts
└── lib/
    └── build.gradle.kts

自Gradle 8.0起，buildSrc已开始表现得更像一个composite build。现在这两种方式基本上是相同的。

很好！😄 等于说提取出来的常见构建逻辑本身就是一个独立的Gradle项目。

事实上，如果你仔细看看构建项目的文件夹结构。

.
├── settings.gradle.kts
└── conventions
    ├── build.gradle.kts
    └── src/main/kotlin/shared-build-conventions.gradle.kts

它看起来就像一个普通的Gradle项目，对吧？

所以，接下来就是precompiled script plugin的真相了。

2.3. precompiled script plugin的真相

你是否曾经好奇为什么precompiled script plugin会被放在src/main/kotlin文件夹中？🤔 就像上面的shared-build-conventions.gradle.kts示例。它能否就留在构建项目的第一层，比如build-logic/shared-build-conventions.gradle.kts？

这里，我想邀请你观看  Jendrik Johannes (jjohannes)的一个视频，标题为Understanding Gradle #25 – Using Java to configure builds。基本上，每个Gradle脚本都是Plugin接口的一个实现。构建脚本build.gradle.kts对应Plugin<Project>，设置脚本settings.gradle.kts对应Plugin<Settings>。

因此，放在src/main/<jvm language>文件夹中的precompiled script plugin也是业务逻辑代码，但这里的业务逻辑是你主项目的构建逻辑。这种代码通常从你的class MyPlugin implements Plugin<Project>实现中的apply(Project project)方法开始。

2.4. 在src/main/kotlin中使用version catalog？🤔

现在，让我们回顾一下gradle/gradle#15383中的声明：

We want to make the version catalogs accessible to precompiled script plugins

翻译过来:

我们希望使version catalog对precompiled script plugin可见

利用我们上面回顾的知识来翻译这句话，它就变成了：

“一个名为libs.versions.toml的文件本意是用在build.gradle.kts文件中。现在我们想在src/main/kotlin文件夹中的业务代码中使用它。”

听起来很奇怪，不是吗？🤔

这就是为什么这个问题很难解决的原因，因为这是一个设计问题，违反了关注点分离原则。

3. 现有的workaround

一些聪明的人提出了几个绝妙的workaround。最著名的一个来自  Björn Kautler (Vampire)的评论，其中你需要添加一个隐秘的Gradle内部文件到dependencies {}块中。这个方法虽然有效，但非常hacky，不能保证在任何Gradle项目中都有效（至少我没弄成功过 😕），在plugins {}块中不起作用，而且这个workaround依赖于一个可能随时变更的Gradle内部API。

还有其他不需要hack的workaround吗？

幸运的是，有一个针对plugins {}块的workaround，如此评论中提到的。由于将外部插件应用到precompiled script plugin需要将外部插件的相应依赖添加到build.gradle.kts文件中，你可以将哪个依赖放进version catalog中。这种方法假设构建项目中的settings.gradle.kts文件导入了与主项目中使用的相同的version catalog。我还发现这种方法适用于设置插件，正如我在此论坛帖子中描述的那样。

我还找到了一个不需要hack的dependencies {}块的workaround，并在此评论中进行了描述。这种workaround利用了Gradle platform和Gradle的构建阶段来实现目的。然而，这种方法非常麻烦，因为添加/移除依赖需要在你的项目中进行三处修改。

总的来说，非hacky的workaround可以覆盖plugins {}块和dependencies {}块。在大多数情况下，这已经足够。但是对于extensions怎么办呢？例如，如果precompiled script plugin应用了Micronaut Gradle插件，如何使用version catalog在micronaut {}扩展中设置Micronaut框架的版本呢？🤷‍♂️

4. 现在开始介绍全新漂亮的workaround 🤩

上面提到的所有workaround或多或少都在做一件事：“发送”原本应该用在Gradle构建脚本中的变量到src/main/kotlin文件夹中的业务代码里。

有一天，我无意中发现了两个Gradle插件：gradle-buildconfig-plugin和BuildKonfig插件。

这两个插件通常用于Kotlin跨平台项目（通常是跨平台Compose应用），用来生成一个包含你在build.gradle.kts脚本中定义的配置变量的Kotlin文件。

例如，如果你有：

plugins {
  // ...
  id("com.github.gmazzo.buildconfig") version <current version>
}

buildConfig {
  className("MyConfig")   // 强制类名。默认为'BuildConfig'
  packageName("com.foo")  // 强制包名。默认为'${project.group}'

  buildConfigField(String::class.java, 'APP_NAME', "my-project")
}
//...

你会得到：

package com.foo

object MyConfig {
  const val APP_NAME: String = "my-project"
}

突然间，我意识到如果我将这个插件应用到构建项目中的build.gradle.kts会怎样？😲

[versions]
java = "21"
slf4j = "2.0.13"

[libraries]
slf4j-api = {module = "org.slf4j:slf4j-api", version.ref = "slf4j"}

plugins {
  // ...
  id("com.github.gmazzo.buildconfig") version <current version>
}

buildConfig {
  className("VersionCatalog")   // 强制类名。默认为'BuildConfig'
  packageName("my.util")  // 强制包名。默认为'${project.group}'

  buildConfigField(Int::class.java, "JAVA_VERSION", libs.versions.java.get().toInt())
  buildConfigField(String::class.java, "SLF4J_API", libs.dep.slf4j.get().toString())
}

那么，我的precompiled script plugin能访问JAVA_VERSION和SLF4J_API变量吗？

你猜怎么着？它居然真的有效！😱

import my.util.VersionCatalog

// 其他配置

java {
  toolchain {
    languageVersion.set(JavaLanguageVersion.of(VersionCatalog.JAVA_VERSION))
  }
}

dependencies {
  implementation(VersionCatalog.SLF4J_API)
}

// 其他配置

5. 结论

利用gradle-buildconfig-plugin或BuildKonfig插件的方法是从precompiled script plugin访问Gradle的version catalog是一个漂亮的workaround。它不是太hacky，能确保在任何Gradle项目中都行得通，而且没有仅在plugins {}块或dependencies {}块可访问的限制。这是一个在你的Gradle项目中集中版本管理的绝佳解决方案。

我希望这个workaround能帮助到你的Gradle项目。如果你有任何问题或建议，欢迎在下面留言。😊