Gluten 新手指南

环境

Gluten 支持 Ubuntu 20.04/22.04、CentOS 7/8 和 MacOS。

JDK

Gluten 针对 Spark 3.4 和 3.5 支持 JDK 8，同时也支持这两个版本的 JDK 11 和 JDK 17。

注意：从 Spark 4.0 开始，最低要求的 JDK 版本为 17。Spark 4.0 及更高版本还支持 JDK 21 和 25。我们建议现在使用更高的 JDK 版本，以便将来为 Spark 4.0 部署 Gluten 时更容易迁移。此外，我们可能会将 Arrow 从 15.0.0 升级到更新的版本，届时将要求最低 JDK 版本为 11。

默认情况下，Gluten 使用 JDK 8 编译打包。通过 -Pjava-17、-Pjava-21、-Pjava-25 或 -Pjava-11 启用相应的 maven profile 以使用对应的 JDK 版本，并确保该 JDK 版本在你的环境中可用。

如果使用 JDK 11 或更高版本，Spark 和 Arrow 需要设置 java 参数 -Dio.netty.tryReflectionSetAccessible=true，参见 SPARK-29924 和 ARROW-6206。

在 spark-defaults.conf 中添加以下配置：

spark.driver.extraJavaOptions=-Dio.netty.tryReflectionSetAccessible=true
spark.executor.extraJavaOptions=-Dio.netty.tryReflectionSetAccessible=true

Maven

Gluten 需要 Maven 3.6.3 或更高版本。

GCC

Gluten 需要 GCC 11 或更高版本。

Dev Container

如果想跳过手动环境配置，可以使用 .devcontainer/ 下的 Dev Container 配置，在预构建的 Docker 镜像中开发 Gluten。有关配置、构建和测试的说明，请参阅 Dev Containers。

开发

要调试 Java/Scala 代码，请按照 build-gluten-with-velox-backend](https://apache.github.io/gluten/get-started/Velox.html#build-gluten-with-velox-backend) 中的步骤操作。

要调试 C++ 代码，请以调试模式编译后端代码和 Gluten 的 C++ 代码。

## compile Velox backend with benchmark and tests to debug
gluten_home/dev/builddeps-veloxbe.sh --build_tests=ON --build_benchmarks=ON --build_type=Debug

注意：要调试 <gluten_home>/gluten-ut/ 下的测试，必须使用 -Pspark-ut 编译 Java 代码。

Java/Scala 代码开发

Linux IntelliJ 本地调试

安装 Linux 版 IntelliJ，进行本地代码调试。

• 请你的 Linux 维护者安装桌面环境，然后重启服务器。

• 如果你使用 Moba-XTerm 连接，则无需安装 x11 服务器。如果你使用的是其他工具（如 putty），请按照本指南操作：X11 Forwarding：Linux 和 Mac 设置说明

• 将 IntelliJ Linux 社区版 下载到 Linux 服务器。

• 使用以下命令启动 Idea：

  bash <idea_dir>/idea.sh

设置 Gluten 项目

• 确保你已经编译了 Gluten。
• 通过 File->Open 加载 Gluten，选择 <gluten_home/pom.xml>。
• 激活你的 profile，例如 <backends-velox>，然后 Reload Maven Project 以激活所有需要的模块。
• 设置断点并按需进行调试。你可以使用 CTRL+N 来查找测试类并开始你的测试。

Java/Scala 代码风格

IntelliJ 支持导入 Java/Scala 代码风格设置。你可以将 intellij-codestyle.xml 导入到你的 IDE 中。参见 IntelliJ 指南。

要使用 Spotless 插件格式化 Java/Scala 代码，请运行以下命令：

./dev/format-scala-code.sh

C++ 代码开发

本指南介绍如何使用 SSH 连接远程 Linux 服务器进行远程调试。

下载并安装 Visual Studio Code。

左侧边栏中的主要组件包括：

• 资源管理器（项目结构）
• 搜索
• 运行和调试
• 扩展（安装 C/C++ Extension Pack、Remote Development 和 GitLens。也建议安装 C++ Test Mate。）
• 远程资源管理器（要使用 ssh 连接到 Linux 服务器，请点击 +，然后输入 ssh USERNAME@REMOTE_SERVER_IP_ADDRESS）
• 管理（设置）

在上面的弹出窗口中输入你的密码。安装过程需要几分钟，Linux 版 VSCode 服务器将被安装到远程机器上的 ~/.vscode-server 文件夹中。

如果下载失败，请删除该文件夹后重试。

注意：如果 VSCode 升级，则必须重新下载 Linux 服务器。我们建议将更新模式切换为 off。在 管理->设置 中搜索 update 以关闭更新模式。

设置项目

• 选择 文件->打开文件夹，然后选择 Gluten 文件夹。
• 项目加载后，系统会提示你 选择 CMakeLists.txt。请选择 ${workspaceFolder}/cpp/CMakeLists.txt 文件。
• 接下来，系统会提示你为 Gluten 项目 选择套件。请选择 GCC 11 或更高版本。

设置

VSCode 支持两种配置用户设置的方式。

• 管理->命令面板（打开 settings.json，通过 Preferences: Open Settings (JSON) 搜索）
• 管理->设置（常用设置）

使用 VSCode 构建

VSCode 将尝试在 <gluten_home>/build 中以调试模式编译。在编译 Gluten 之前，你必须先以调试模式编译 Velox。

注意：如果你之前以发布模式编译过 Velox，请使用以下命令以调试模式编译。

cd gluten/ep/build-velox/build/velox_ep

# Build the Velox debug version in <velox_home>/_build/debug
make debug EXTRA_CMAKE_FLAGS="-DVELOX_ENABLE_PARQUET=ON -DENABLE_HDFS=ON -DVELOX_BUILD_TESTING=OFF  -DVELOX_ENABLE_DUCKDB=ON -DVELOX_BUILD_TEST_UTILS=ON"

然后 Gluten 会链接 Velox 调试库。

点击底部栏中的 build，以启用智能感知（IntelliSense）功能，如搜索和导航。

调试设置

默认的编译命令不会启用测试和基准测试，因此不会生成相应的可执行文件。要启用测试和基准测试参数，请创建或编辑 <gluten_home>/.vscode/settings.json，并添加以下配置：

{
    "cmake.configureArgs": [
        "-DBUILD_BENCHMARKS=ON",
        "-DBUILD_TESTS=ON"
    ],
    "C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools"
}

使用这些更新后的配置编译完成后，你应该会得到可执行文件，例如 <gluten_home>/cpp/build/velox/tests/velox_shuffle_writer_test。

打开 Run and Debug（运行和调试）面板（Ctrl-Shift-D），然后点击链接创建一个 launch.json 文件。如果出现提示，请选择一个调试器，例如 C++ (GDB/LLDB)。launch.json 将创建在 <gluten_home>/.vscode/ 下。

注意：请根据你的环境修改 name、program、args。

点击 launch.json 中的 Add Configuration 按钮，并选择 gdb 的 launch 来启动程序进行调试，或选择 attach 附加到正在运行的程序进行调试。

之后，你就可以设置断点，并在 Visual Studio Code 中通过 Run and Debug 进行调试。

调试 Velox 代码

对于某些 Velox 测试（例如 ParquetReaderTest），测试需要读取 <velox_home>/velox/dwio/parquet/tests/examples 中的 parquet 文件。请在 IDE 窗口中选择 ParquetReaderTest.cpp，然后点击 Start Debugging（开始调试），否则将会抛出 No such file or directory 异常。

Clang format

Gluten 使用 clang-format 15 来格式化源文件。

apt-get install clang-format-15

在 settings.json 中设置配置

"clang-format.executable": "clang-format-15",
"editor.formatOnSave": true,

如果安装了多个 clang-format 版本，formatOnSave 可能不会生效。要指定默认格式化程序，请在 Settings 中搜索 default formatter，然后选择 Clang-Format。

如果 formatOnSave 仍然无效，请选中单个文件，然后使用 SHIFT+ALT+F 手动对其进行格式化。

CMake 格式化

要格式化 CMakeLists.txt 和 *.cmake 等 cmake 文件，请安装 cmake-format。

pip3 install --user cmake-format

以下是使用命令行格式化文件的示例：

cmake-format --first-comment-is-literal True --in-place cpp/velox/CMakeLists.txt

完成上述安装后，你可以选择在 Visual Studio Code 中进行一些配置，以便轻松格式化 cmake 文件。

1. 在 Visual Studio Code 中安装 cmake-format 扩展。

2. 配置该扩展。为此，打开设置（文件 -> 首选项 -> 设置），搜索 cmake-format，并按如下所示配置以下设置：

   • 将 Args 设置为：--first-comment-is-literal=True。
   • 将 Exe Path 设置为 cmake-format 命令的路径。如果你将 cmake-format 安装在标准位置，则可能无需更改此设置。

3. 在文件中右键单击并选择 Format Document 来格式化你的 CMake 文件。

添加单元测试

1. 针对原生代码的修改：如果你修改了原生代码，请使用 gtest 测试原生代码。次要选项是添加 Gluten UT 以确保覆盖率。
2. 针对 Gluten 相关代码的修改：如果你修改了与 Gluten 相关的代码，最好添加 scalatest 而不是 JUnit。此外，测试类应放置在 org.apache.gluten 包中。
3. 针对 Spark 相关代码的修改：如果你修改了与 Spark 相关的代码，最好添加 scalatest 而不是 JUnit。此外，测试类应放置在 org.apache.spark 包中。
4. 非原生代码 UT 的放置位置：请确保非原生代码的单元测试放置在 org.apache.gluten 和 org.apache.spark 包中。这一点很重要，因为 CI 系统会并行运行来自这两个路径的单元测试。将测试放置在其他路径中可能会导致你的测试被忽略。

在 GHA 中查看 Scala 单元测试的 Surefire 报告

Surefire 报告是使用 Maven 构建自动化工具的 Java 应用生态系统中不可或缺的工具。
这些报告由 Maven Surefire 插件在构建过程的测试阶段生成。
它们汇总了单元测试的结果，提供了有关哪些测试通过或失败、遇到了哪些错误以及其他关键指标的详细信息。

Surefire 报告在高质量软件的开发和维护中发挥着至关重要的作用。
在 GitHub Actions 中，我们公开 Surefire 测试报告，以便开发者可以查看失败单元测试的错误信息和堆栈跟踪。

要查看 Surefire 报告：

1. 在 PR 中点击 Checks 标签页。
2. 在 Dev PR 中找到 Report test results。
3. 在那里，你可以查看带有摘要和注释的结果。

Mac 开发

编译

Gluten 不提供 macOS 的预编译 JAR 包。不过，你可以自行编译，并在本地使用 IDE 进行运行或调试。

首先，设置依赖的安装前缀：

export INSTALL_PREFIX=$HOME/velox/deps-install

所有 Velox 相关的库都将安装在 INSTALL_PREFIX 所指定的目录下。

使用以下命令构建 Gluten。请注意，在 macOS 上必须禁用测试（–build_tests=OFF），因为部分测试无法成功运行。

# Build velox and gluten-cpp
./dev/builddeps-veloxbe.sh --run_setup_script=ON --build_arrow=ON --build_tests=OFF
# Build java code
mvn clean install -Pbackends-velox -Pspark-3.4 -DskipTests

注意：请按照 build-gluten-with-velox-backend 中的步骤操作。

构建完成后，你可以使用 IDE 在本地运行和调试 Gluten。

Intellij 调试

Intellij 执行单元测试需要两项额外配置。

1. 将 JDK 设置为 Azul zulu - aarch64

1. 将 Scala 编译器 Incrementality type 设置为 IDEA

使用核心转储（Core Dump）调试 C++ 代码

mkdir -p /mnt/DP_disk1/core
sysctl -w kernel.core_pattern=/mnt/DP_disk1/core/core-%e-%p-%t
cat /proc/sys/kernel/core_pattern
# set the core file to unlimited size
echo "ulimit -c unlimited" >> ~/.bashrc
# then you will get the core file at `/mnt/DP_disk1/core` when the program crashes
# gdb -c corefile
# gdb <gluten_home>/cpp/build/releases/libgluten.so 'core-Executor task l-2000883-1671542526'

core-Executor task l-2000883-1671542526 是生成的核心文件名。

(gdb) bt
(gdb) f7
(gdb) set print pretty on
(gdb) p *this

• 获取回溯信息
• 切换到第 7 层栈帧
• 以更易读的方式打印变量
• 打印变量的各个字段

有时你只能看到 C++ 异常消息。如果遇到这种情况，可以通过运行以下代码生成 core dump 文件：

char* p = nullptr;
*p = 'a';

或通过以下命令：

• gcore <pid>
• kill -s SIGSEGV <pid>

使用 GDB 调试 C++

你可以使用 GDB 调试测试、基准测试和 JNI 调用。将以下代码放入你的调试路径中。

pid_t pid = getpid();
printf("----------------------------------pid: %lun", pid);
sleep(10);

你也可以在执行单元测试时，通过 java 命令或 grep java 进程来获取 pid。

jps
1375551 ScalaTestRunner
ps ux | grep TestOperator

执行 GDB 命令以调试：

gdb attach <pid>

gdb attach 1375551
wait to attach....
(gdb) b <velox_home>/velox/substrait/SubstraitToVeloxPlan.cpp:577
(gdb) c

调试内存泄漏

Arrow 内存分配器泄漏

如果你收到类似如下的错误信息：

4/04/18 08:15:38 WARN ArrowBufferAllocators$ArrowBufferAllocatorManager: Detected leaked Arrow allocator [Default], size: 191, process accumulated leaked size: 191...
24/04/18 08:15:38 WARN ArrowBufferAllocators$ArrowBufferAllocatorManager: Leaked allocator stack Allocator(ROOT) 0/191/319/9223372036854775807 (res/actual/peak/limit)

你可以通过添加 VP 选项 -Darrow.memory.debug.allocator=true 来打开 Arrow 分配器的调试配置。这样你能获得更多详细信息，示例如下：

child allocators: 0
  ledgers: 7
    ledger[10] allocator: ROOT), isOwning: , size: , references: 1, life: 10483701311283711..0, allocatorManager: [, life: ] holds 1 buffers.
        ArrowBuf[11], address:140100698555856, capacity:128
     event log for: ArrowBuf[11]
       10483701311362601 create()
              at org.apache.arrow.memory.util.HistoricalLog$Event.<init>(HistoricalLog.java:175)
              at org.apache.arrow.memory.util.HistoricalLog.recordEvent(HistoricalLog.java:83)
              at org.apache.arrow.memory.ArrowBuf.<init>(ArrowBuf.java:97)
              at org.apache.arrow.memory.BufferLedger.newArrowBuf(BufferLedger.java:271)
              at org.apache.arrow.memory.BaseAllocator.bufferWithoutReservation(BaseAllocator.java:340)
              at org.apache.arrow.memory.BaseAllocator.buffer(BaseAllocator.java:316)
              at org.apache.arrow.memory.RootAllocator.buffer(RootAllocator.java:29)
              at org.apache.arrow.memory.BaseAllocator.buffer(BaseAllocator.java:280)
              at org.apache.arrow.memory.RootAllocator.buffer(RootAllocator.java:29)
              at org.apache.arrow.c.ArrowArray.allocateNew(ArrowArray.java:116)
              at org.apache.arrow.c.ArrayImporter.importArray(ArrayImporter.java:61)
              at org.apache.arrow.c.Data.importIntoVector(Data.java:289)
              at org.apache.arrow.c.Data.importIntoVectorSchemaRoot(Data.java:332)
              at org.apache.arrow.dataset.jni.NativeScanner$NativeReader.loadNextBatch(NativeScanner.java:151)
              at org.apache.gluten.datasource.ArrowFileFormat$$anon$1.hasNext(ArrowFileFormat.scala:99)
              at org.apache.gluten.utils.IteratorCompleter.hasNext(Iterators.scala:69)
              at org.apache.spark.memory.SparkMemoryUtil$UnsafeItr.hasNext(SparkMemoryUtil.scala:246)

C++ 代码内存泄漏

有时在调试内存泄漏时无法获取 coredump 符号。此时可以编写一个 GoogleTest，使用 valgrind 进行检测。

apt install valgrind
valgrind --leak-check=yes ./exec_backend_test

运行 TPC-H 和 TPC-DS

我们提供了 <gluten_home>/tools/gluten-it 来执行这些查询。请参阅 velox_backend_x86.yml。

为 Spark 启用 Gluten

要为 Spark 启用 Gluten Velox 后端，请运行以下命令：

spark-shell --name run_gluten \
 --master yarn --deploy-mode client \
 --conf spark.plugins=org.apache.gluten.GlutenPlugin \
 --conf spark.memory.offHeap.enabled=true \
 --conf spark.memory.offHeap.size=20g \
 --jars https://dlcdn.apache.org/gluten/1.6.0/apache-gluten-1.6.0-bin-spark-3.5.tar.gz \
 --conf spark.shuffle.manager=org.apache.spark.shuffle.sort.ColumnarShuffleManager

Gluten 计划的校验与更新

VeloxTPCHSuite 可以校验 TPC-H 基准测试中已执行的 Gluten 计划，以避免出现非预期的改动。该校验基于与记录了预期 Gluten 计划的黄金文件（golden files）进行比对。

在 GitHub CI 或本地测试中可能会出现以下失败：

- TPC-H q5 *** FAILED ***
  Mismatch for query 5
  Actual Plan path: /tmp/tpch-approved-plan/v1-bhj/spark35/5.txt
  Golden Plan path: /opt/gluten/backends-velox/target/scala-2.12/test-classes/tpch-approved-plan/v1-bhj/spark35/5.txt (VeloxTPCHSuite.scala)

要更新 golden 文件，请在 GitHub CI Artifacts 或本地的 /tmp/ 目录中找到实际的 Gluten 计划，然后更新 tpch-approved-plan/ 目录中对应的 golden 文件。