Bloop 集成以加速 Scala 构建

Bloop 是一个 Scala 构建服务器，它通过维护一个具有预热编译器状态的常驻 JVM，显著加快了增量编译速度。对于 Gluten 开发而言，这消除了每次 Maven 构建时都会出现的约 52 秒 Zinc 分析加载开销。

优势

持久化增量编译：Bloop 使 Zinc 的增量编译器状态保持预热
监听模式：文件变更时自动重新编译（bloop compile -w）
快速测试迭代：重复运行测试时跳过 Maven 的开销
IDE 集成：Metals/VS Code 可以使用 Bloop 进行构建

前置条件

安装 Bloop CLI

选择以下任意一种安装方式：

# Using Coursier (recommended)
cs install bloop

# Using Homebrew (macOS)
brew install scalacenter/bloop/bloop

# Using SDKMAN
sdk install bloop

# Manual installation
# See https://scalacenter.github.io/bloop/setup

验证安装：

bloop --version

设置

生成 Bloop 配置

使用所需的 Maven profile 运行设置脚本：

# Velox backend with Spark 3.5
./dev/bloop-setup.sh -Pspark-3.5,scala-2.12,backends-velox

# Velox backend with Spark 4.0 (requires JDK 17)
./dev/bloop-setup.sh -Pjava-17,spark-4.0,scala-2.13,backends-velox,spark-ut

# ClickHouse backend
./dev/bloop-setup.sh -Pspark-3.5,scala-2.12,backends-clickhouse

# With optional modules
./dev/bloop-setup.sh -Pspark-3.5,scala-2.12,backends-velox,delta,iceberg

这将生成包含每个 Maven 模块的 JSON 配置文件的 .bloop/ 目录。

直接使用 Maven Profile

-Pbloop profile 会在生成配置时自动跳过样式检查。你可以直接在 Maven 中使用它：

# These are equivalent:
./dev/bloop-setup.sh -Pspark-3.5,scala-2.12,backends-velox

# Manual invocation with profile
./build/mvn generate-sources bloop:bloopInstall -Pspark-3.5,scala-2.12,backends-velox,fast-build -DskipTests

bloop profile 会自动设置以下属性：

spotless.check.skip=true
scalastyle.skip=true
checkstyle.skip=true
maven.gitcommitid.skip=true
remoteresources.skip=true

注意： 安装脚本还会注入 JVM 选项（例如 --add-opens 标志），这些选项是 Java 17+ 上运行 Spark 测试所必需的。如果不使用脚本而手动运行 bloop:bloopInstall，测试可能会因 IllegalAccessError 而失败。请使用安装脚本以确保配置正确。

常见 Profile 组合

使用场景	Profile
Spark 3.5 + Velox	`-Pspark-3.5,scala-2.12,backends-velox`
Spark 4.0 + Velox	`-Pjava-17,spark-4.0,scala-2.13,backends-velox`
Spark 4.1 + Velox	`-Pjava-17,spark-4.1,scala-2.13,backends-velox`
运行单元测试	在任意 Profile 后添加 `,spark-ut`
ClickHouse 后端	将 `backends-velox` 替换为 `backends-clickhouse`
使用 Delta Lake	在任意 Profile 后添加 `,delta`
使用 Iceberg	在任意 Profile 后添加 `,iceberg`

使用方法

基本命令

# List all projects
bloop projects

# Compile a project
bloop compile gluten-core

# Compile with watch mode (auto-recompile on changes)
bloop compile gluten-core -w

# Compile all projects
bloop compile --cascade gluten-core

# Run tests
bloop test gluten-core

# Run specific test suite
bloop test gluten-ut-spark35 -o GlutenSQLQuerySuite

# Run tests matching pattern
bloop test gluten-ut-spark35 -o '*Aggregate*'

运行测试

使用便捷包装器以匹配 run-scala-test.sh 接口：

# Run entire suite
./dev/bloop-test.sh -pl gluten-ut/spark35 -s GlutenSQLQuerySuite

# Run specific test method
./dev/bloop-test.sh -pl gluten-ut/spark35 -s GlutenSQLQuerySuite -t "test method name"

# Run with wildcard pattern
./dev/bloop-test.sh -pl gluten-ut/spark40 -s '*Aggregate*'

环境变量

直接使用 bloop 运行测试（而非通过 bloop-test.sh）时，请设置以下环境变量：

# Required for Spark 4.x tests - disables ANSI mode which is incompatible with some Gluten features
export SPARK_ANSI_SQL_MODE=false

# If bloop uses wrong JDK version, set JAVA_HOME before starting bloop server
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
bloop exit && bloop about  # Restart server with new JDK

# Then run tests
bloop test backends-velox -o '*VeloxHashJoinSuite*'

注意：bloop-test.sh 包装器会自动设置 SPARK_ANSI_SQL_MODE=false。

用于快速开发的监视模式

监视模式非常适合迭代开发：

# Terminal 1: Start watch mode for your module
bloop compile gluten-core -w

# Terminal 2: Edit files and see instant compilation feedback
# Errors appear immediately as you save files

对比：Bloop 与 Maven

对比项	Maven	Bloop
首次编译	基准	相同（需要完整构建）
增量编译	约 52 秒以上（Zinc reload）	小于 5 秒（热 JVM）
监听模式	不支持	原生支持
测试执行	完整的 Maven 生命周期	直接执行
IDE 集成	有限	Metals/VS Code 原生支持
Profile 切换	修改命令	重新运行设置脚本

何时使用哪种工具

使用 Bloop 的场景：

开发过程中的快速迭代
反复运行测试
希望对代码修改获得即时反馈
使用 Metals/VS Code

使用 Maven 的场景：

CI/CD 构建
完整的发布构建
首次环境设置
在不同 profile 组合之间切换
需要 Maven 专属插件

IDE 集成

VS Code 与 Metals

在 VS Code 中安装 Metals 扩展
生成 bloop 配置：./dev/bloop-setup.sh -P<profiles>
在 VS Code 中打开项目文件夹
Metals 会检测到 .bloop/ 并将其用于构建

IntelliJ IDEA

IntelliJ 默认使用自带的增量编译器。不过，你也可以：

在终端中执行 bloop 命令
配置 IntelliJ 使用 BSP（Build Server Protocol）配合 bloop

故障排查

“Bloop project not found”

Error: Bloop project 'gluten-ut-spark35' not found

该项目未包含在生成的配置中。请使用正确的 profile 重新生成：

# Make sure to include the spark-ut profile for test modules
./dev/bloop-setup.sh -Pspark-3.5,scala-2.12,backends-velox,spark-ut

“找不到 Bloop CLI”

Error: Bloop CLI not found. Install with: cs install bloop

安装 bloop CLI：

# Using Coursier
cs install bloop

# Or check if it's in your PATH
which bloop

配置不同步

如果编译时出现意外错误导致失败，请重新生成配置：

# Remove old config
rm -rf .bloop

# Regenerate
./dev/bloop-setup.sh -P<your-profiles>

Bloop 服务器问题

# Restart bloop server
bloop exit
bloop about  # This starts a new server

# Or kill all bloop processes
pkill -f bloop

配置文件不匹配

请记住，bloop 配置是针对特定的一组 Maven profile 生成的。如果需要切换 profile：

# Switching from Spark 3.5 to Spark 4.0
./dev/bloop-setup.sh -Pjava-17,spark-4.0,scala-2.13,backends-velox,spark-ut

高级用法

并行编译

Bloop 会自动进行并行编译。可通过以下方式控制：

# Limit parallelism
bloop compile gluten-core --parallelism 4

清理构建

# Clean specific project
bloop clean gluten-core

# Clean all projects
bloop clean

依赖关系图

# Show project dependencies
bloop projects --dot | dot -Tpng -o deps.png

注意事项

配置不提交到版本库：.bloop/ 默认位于 .gitignore 中，这是有意为之
与 Profile 相关：更改 Maven profile 时必须重新生成配置
与 Maven 互补：Bloop 加速开发迭代；Maven 仍用于 CI／生产构建
首次运行较慢：初次 bloopInstall 会执行完整的 Maven 依赖解析

Bloop 集成以加快 Scala 构建