在 Dev 容器中开发 Gluten

Gluten 提供了两套 Dev Container 配置，分别用于日常的 Velox 开发和静态链接打包。两者都基于已预装原生依赖栈的镜像，且都不会在容器创建时构建 Gluten。

前置条件

Docker、VS Code及其 Dev Containers 扩展，或者支持 Codespaces 的账号。

选择配置

在 VS Code 中，从命令面板（F1）运行 Dev Containers: Reopen in Container，然后选择一个配置。在 Codespaces 中，打开 Create codespace with options，并在创建 codespace 之前选择配置。

共享的 post-create 脚本会安装缺失的开发工具、为机器确定 NUM_THREADS 的大小，并输出所选配置对应的命令。

原生构建不会自动执行。 该构建耗时从几十分钟到数小时不等；如果编辑器断开连接或 Codespace 超时，它会阻塞容器创建流程，并留下一个构建到一半的源码树。

Velox 动态链接开发

默认配置使用 apache/gluten:centos-9-jdk8。它包含动态链接的依赖、位于 /usr/local 下的 Arrow、预热的 Maven 仓库，以及位于 /opt/shims 下的 Spark 发行版。

构建原生后端和 Spark 3.5 的 jar：

./dev/buildbundle-veloxbe.sh --run_setup_script=OFF --build_arrow=OFF \
                             --build_tests=ON --spark_version=3.5

为 Spark 4.1 构建

Spark 4.0/4.1 需要 JDK 17 和 Scala 2.13。动态镜像默认使用 JDK 8，而 post-create.sh 会在其旁边安装 JDK 17。在开始构建之前，请先切换正在使用的 JDK：

export JAVA_HOME=/usr/lib/jvm/java-17-openjdk
export PATH="$JAVA_HOME/bin:$PATH"
java -version  # must report 17

./dev/buildbundle-veloxbe.sh --run_setup_script=OFF --build_arrow=OFF \
                             --build_tests=ON --spark_version=4.1

buildbundle-veloxbe.sh 增加了 -Pjava-17、-Pscala-2.13 以及面向 Spark 4.x 的 Java 17 发布目标，但 Maven profile 无法切换当前正在运行的 JDK。如果 JDK 8 仍然处于启用状态，Scala 将报错：

scalac error: '17' is not a valid choice for '-release'

重新构建原生代码

修改 C++ 代码后：

./dev/builddeps-veloxbe.sh --run_setup_script=OFF --build_arrow=OFF \
                           --build_tests=ON build_velox build_gluten_cpp

当仅 Gluten 自身位于 cpp/ 下的 C++ 代码发生变动时，去掉 build_velox。保持 --build_tests 与原始构建一致：build_gluten_cpp 会清除 cpp/build，因此省略它同样会移除 C++ 测试二进制文件。

运行测试

在 JDK 17 上运行 Spark 3.5 测试套件：

export JAVA_HOME=/usr/lib/jvm/java-17-openjdk
export PATH="$JAVA_HOME/bin:$PATH"

./build/mvn test -Pspark-ut -Pbackends-velox -Pspark-3.5 -Pjava-17 \
    -DargLine="-Dspark.test.home=/opt/shims/spark35/spark_home/" \
    -DwildcardSuites=org.apache.spark.sql.GlutenSQLQuerySuite

-DwildcardSuites 接受一个完全限定类名，并将一次运行控制在几分钟内。不要添加 -pl gluten-ut：它只会选中聚合 POM，不会运行任何测试套件。更多信息参见 HowTo。

使用 --build_tests=ON 构建完成后，运行 C++ 单元测试：

cd cpp/build && ctest -V

Velox 静态链接打包

静态配置使用 apache/gluten:vcpkg-centos-9。它无需构建 Gluten 即可打开，并且在容器重建之间保留镜像的 vcpkg 二进制缓存。

构建一个可移植的 Spark 3.5 jar：

./dev/buildbundle-veloxbe.sh --enable_vcpkg=ON --build_arrow=OFF \
                             --spark_version=3.5

S3、GCS、HDFS 和 ABFS 默认是禁用的。只启用该 jar 所需的功能：

./dev/buildbundle-veloxbe.sh --enable_vcpkg=ON --build_arrow=OFF \
    --spark_version=3.5 --enable_s3=ON

每个已启用的 feature 可能会恢复或构建额外的 vcpkg ports。vcpkg 通过 ABI 哈希对 ports 进行缓存；更改编译器、triplet 或相关的 port 输入会使该缓存失效。在此打包流程中会禁用本地测试二进制文件。

该静态镜像默认使用 JDK 17。对于 Spark 4.1：

java -version  # must report 17

./dev/buildbundle-veloxbe.sh --enable_vcpkg=ON --build_arrow=OFF \
                             --spark_version=4.1

静态镜像不包含 /opt/shims；Spark 单元测试请使用动态配置。在 arm64 上，post-create.sh 还会自动选择 arm64 的 vcpkg triplet 并启用所需的系统二进制文件。

构建并行度

builddeps-veloxbe.sh 将 NUM_THREADS 默认设为 nproc --ignore=2，该值不考虑内存。Velox 中较重的翻译单元每个约占 3.5 GB，因此在核心数较多的机器上可能触发 OOM killer。post-create.sh 会导出一个值，使每个任务约占 4 GB，并在每次打开 shell 时重新计算，因此它也会随之适应调整过大小的 Codespace。

显式设置的 export NUM_THREADS=<n> 仍然优先。VS Code 任务不会读取 ~/.bashrc，因此请在任务中传入 --num_threads=<n>。

在配置之间切换

静态与动态构建树不可互换：cpp/build/CMakeCache.txt 记录了 vcpkg 工具链，ep/build-velox/build/velox_ep/_build/ 记录了依赖链接方式。切换后请移除镜像特有的状态：

rm -rf cpp/build ep/build-velox/build/velox_ep/_build ep/_ep \
       dev/vcpkg/.vcpkg dev/vcpkg/vcpkg_installed

这些配置使用相互独立的 ccache、Maven 和 vcpkg 缓存卷，因此重新构建一个环境不会污染另一个环境。

机器规格

动态配置请求 4 个 CPU、16 GB 内存和 64 GB 存储；静态配置请求 8 个 CPU、64 GB 内存和 64 GB 存储，因为静态链接需要更多内存。

只有 Codespaces 会遵循 hostRequirements；对于本地开发，请自行调整 Docker 虚拟机的规格。

镜像

已发布的镜像可在 Docker Hub 上获取；其 Dockerfile 位于 dev/docker/，并在 Velox 后端 CI 中有相关说明。

若要在 Dev Container 之外使用这些镜像，请参阅 在 docker 中构建 Gluten Velox 后端。