Blossom插件的使用

Blossom Gradle 插件文档翻译

Blossom GitHub主页

---

Blossom 是一个 Gradle 插件，用于将源模板处理成多种语言的资源和源代码。它基于 LGPL v2.1 许可证授权。

使用方法

将插件应用到您的项目中。Blossom 至少需要 Java 11。它会在 Gradle 当前主要版本的最新修订版和上一个主要版本的最新修订版上进行测试，但我们的开发重点放在较新的 Gradle 版本上。

plugins {id("net.kyori.blossom") version "2.2.0"
}

Blossom 在每个源集上添加了 blossom 扩展，允许配置该源集的模板处理。默认情况下不启用任何模板集。

可以使用 Pebble 模板语言对文件名和源文件进行模板化处理。

资源模板化

调用 blossom 扩展上的 resources() 方法来开始应用资源模板：

version = "1.4.0-SNAPSHOT"sourceSets {main {blossom {resources {property("version", project.version.toString())}}}
}

[!重要]
处理模板时，Pebble 会修剪模板标签后的换行符。
当使用 YAML 或 Java 属性文件等格式时，这可能不是期望的行为，因此 Blossom 提供了一种禁用此行为的方法：

在模板集块中添加 trimNewlines = false 行，将禁用该集合中任何模板的换行符修剪。

然后将文件放在 src/main/resource-templates 文件夹中：

build-vars.properties：

version={{ version }}

当项目构建时，build-vars.properties 文件将被处理成最终的资源：

version=1.4.0-SNAPSHOT

源代码模板化

源代码模板化的工作方式类似，但由于支持多种 JVM 语言，稍微复杂一些：

build.gradle.kts：

sourceSets {main {blossom {javaSources {property("version", project.version.toString())property("gitCommit", indraGit.commit.map { it.name() }.orNull())property("decompilerVersion", libs.versions.vineflower.get())}}}
}

src/main/java-templates/net/kyori/blossomtest/BuildParameters.java.peb：

package net.kyori.blossomtest;class BuildParameters {public static final String VERSION = "{{ version }}";public static final String GIT_COMMIT = "{{ gitCommit | default("unknown") }}";public static final String DECOMPILER_VERSION = "{{ decompilerVersion }}";
}

BuildParameters 类将被处理，并可供编译的其他文件使用。

变体和参数文件

虽然模板本身已经可以生成很多内容，但 Blossom 通过变体增加了额外的强大功能。每个模板集可以具有默认变体，或者几个命名变体，它们使用相同的模板但使用不同的输入变量来生成输出。当与模板化的文件名结合使用时，这允许从一个输入生成大量不同的源文件（例如，处理 Java 基本类型时）。

属性和属性文件可以针对每个模板集单独设置，也可以针对每个变体设置。

例如：

build.gradle.kts：

sourceSets {main {blossom {javaSources {propertyFile("template-vars.yaml")variants("float", "int", "double")}}}
}

template-vars.yaml：

type: potato # 在所有变体间共享# 如果存在多个变体，`variants` 键具有特殊含义 - 每个子键应匹配一个变体的名称。
# 每个变体下的值是该变体特有的属性。
variants:float:suffix: "f"wrapper: "Float"int:suffix: ""wrapper: "Integer"double:suffix: "d"wrapper: "Double"

这将处理所有模板三次，每个变体一次 —— 因此 src/main/java-templates/{{ wrapper }}Box.java.peb 将生成三个类文件：

• FloatBox.java
• IntegerBox.java
• DoubleBox.java

IDE 集成

首次导入 IDE 时，您可能需要运行 generateTemplates 任务以确保模板已生成。

Eclipse

在 Eclipse 中，此任务被注册为"同步"任务，每次项目与 Gradle 同步时都会更新模板。

IntelliJ

对于 IntelliJ 集成，还需要添加 https://github.com/JetBrains/gradle-idea-ext-plugin 插件，Blossom 将自动配置适当的导入后钩子。

回答问题

这个插件是干嘛的？

Blossom 是一个 Gradle 插件，主要用于在构建过程中进行模板化处理。 它的核心功能是：

1. 资源模板化：处理资源文件（如 .properties, .yaml 等），将模板中的占位符替换为实际的值。
2. 源代码模板化：处理源代码文件（如 .java, .kt 等），根据模板生成实际的源代码文件。
3. 支持变体：一个强大的功能是支持"变体"，允许你使用同一套模板，但传入不同的参数集，从而生成多个版本的文件。

简单来说，它让你能够用模板来生成项目中的资源文件和源代码文件，从而避免重复代码，并使构建过程更加动态和可配置。

怎么使用这个插件？

使用 Blossom 插件的基本步骤如下：

1. 应用插件：在项目的 build.gradle.kts 文件中应用插件。

   plugins {id("net.kyori.blossom") version "2.2.0"
   }
   

2. 配置模板集：在相应的源集（如 main）的 blossom 扩展中配置模板处理。

   • 对于资源模板：使用 resources { ... } 块
   • 对于源代码模板：使用 javaSources { ... } 块

3. 定义属性：在配置块中，使用 property("key", value) 方法定义模板中可用的变量。

4. 创建模板文件：

   • 将资源模板文件放在 src/<sourceSetName>/resource-templates/ 目录下
   • 将源代码模板文件放在 src/<sourceSetName>/java-templates/ 目录下
   • 模板文件使用 Pebble 语法（如 {{ variableName }}）

5. 构建项目：当运行构建时，Blossom 会自动处理模板文件，生成最终的文件。

高级用法：

• 使用 variants() 方法创建多个变体
• 使用 propertyFile() 从外部文件加载属性
• 配置 trimNewlines = false 来禁用换行符修剪

IDE 集成：

• 对于 IntelliJ，需要添加 org.jetbrains.gradle.plugin.idea-ext 插件
• 对于 Eclipse，Blossom 会自动配置同步任务
• 首次导入时可能需要手动运行 generateTemplates 任务

Blossom 处理特殊文件的能力分析

Blossom 的核心能力

Blossom 主要是一个模板处理工具，而不是通用的文本替换工具。 它的设计初衷是基于模板生成文件，而不是修改现有文件的内容。

可以处理的情况

1. 模板文件处理：Blossom 可以处理任何文本文件作为模板

   • 支持 .properties、.yaml、.xml、.json 等配置文件
   • 支持 .java、.kt 等源代码文件
   • 支持任何纯文本格式

2. 基于模板的字符替换：在模板文件中，你可以使用 Pebble 语法进行复杂的替换

   # 示例：替换特定字符为指定格式
   版本号: {{ version | replace(".", "-") }}
   日期: {{ "now" | date("YYYY-MM-DD") }}
   

3. 条件性替换：可以根据条件决定替换内容

   {% if production %}
   debug: false
   log_level: WARN
   {% else %}
   debug: true
   log_level: DEBUG
   {% endif %}
   

局限性

Blossom 不能直接做到：

1. 修改现有文件：它不会修改已存在的文件，而是从模板生成新文件
2. 部分内容替换：无法只替换文件中的某几个字符，保留其他内容不变
3. 原地编辑：所有处理都是"模板 → 输出"的模式

替代方案

如果你需要更灵活的文本处理，可以考虑：

1. Gradle 的 Copy 任务 + 过滤：

   tasks.register<Copy>("processFiles") {from("src/main/resources")into("build/resources")filter { line ->line.replace("OLD_TEXT", "NEW_TEXT")}
   }
   

2. 使用专门的文本处理插件：

   • gradle-text-processor 插件
   • 自定义 Groovy/Java 代码进行文本处理

3. 结合多种工具：

   // 先用 Blossom 生成模板，再用其他方式进一步处理
   tasks.named("generateTemplates") {doLast {// 对生成的文件进行额外处理}
   }
   

总结

Blossom 适合：基于模板生成完整文件，特别是需要根据构建参数动态生成内容的情况。

Blossom 不适合：对现有文件进行部分修改、字符级替换、或者复杂的文本转换操作。

如果你需要替换某个文件的特定字符为指定格式，建议使用 Gradle 的原生文件处理功能或其他专门的文本处理工具。