企业官网建设流程全解析

• 数据工程
• 大数据
• 序列化
• 数据分析

导读

本文以 Apache Arrow 仓库dev/conbench_envs目录为核心，系统讲解 Arrow 项目如何为 conbench 基准测试系统准备多语言（C++/Python/R/Java/JavaScript）构建环境与运行环境。你将掌握benchmarks.env中每个构建参数的真实作用、hooks.sh中每个 hook 函数的实现细节，以及一条从安装系统依赖到运行各语言 micro-benchmark 的完整可复现流程——既能支撑 CI 中@ursabot please benchmark自动化评测，也能在本地手工搭建同款基准测试环境。

一、目录定位：基准测试的"环境即代码"

在 Apache Arrow 仓库中，dev/conbench_envs目录承担着把基准测试环境声明为版本化代码的职责，包含两个核心文件：

• benchmarks.env：用于构建 Arrow C++/Python/R/Java/JavaScript 并运行 conbench 基准测试的环境变量清单；
• hooks.sh：被@ursabot基准测试构建调用的 hook 函数集，负责创建 conda 环境、从源码编译 Arrow 各语言绑定。

1.1 自动化触发的完整闭环

整个自动化基准测试的流程是：

1. 开发者创建apache/arrowPR；
2. 修改或新增 benchmarks.env 中的环境变量；
3. 在 PR 下评论@ursabot please benchmark触发基准构建；
4. 构建完成后，PR 评论中会出现 compare/runs 链接，其中：
   • baseline= PR 基线的 HEAD commit，使用未改动的dev/conbench_envs/benchmarks.env；
   • contender= PR 分支的 HEAD commit，使用被覆盖后的dev/conbench_envs/benchmarks.env。

通过对比 baseline 与 contender 的基准结果，Arrow 贡献者可以量化评估不同构建选项、依赖版本对性能的影响。

1.2 为什么需要hooks.sh？

@ursabot的基准测试构建托管在 Ursa 的私有仓库中，而构建逻辑本身（创建 conda 环境、编译 Arrow 各语言）必须在 Arrow 仓库内定义。将 hook 定义在 Arrow 仓库中，可以保证某个 commit 的基准构建与该 commit 内用于安装依赖和构建 Arrow 的脚本天然兼容——因为 hook 函数引用的ci/conda_env_*.txt、ci/scripts/*.sh等文件都取自被评测的同一个 commit。

这正是该设计的精妙之处：Arrow 贡献者通过修改hooks.sh，即可评估不同构建选项、依赖版本、编译器配置的性能影响，而无需改动任何 CI 基础设施。

二、benchmarks.env：基准构建参数逐项解析

benchmarks.env 本质是一份 shell 风格的环境变量清单，由hooks.sh中的set_arrow_build_and_run_env_vars()通过source加载，并通过set -a/set +a自动导出为全局变量。其内容与 ci/scripts/cpp_build.sh 中cmake的参数名一一对应，可直接映射到 CMake 配置项。

2.1 构建类型与组件开关

2.2 功能模块开关

这些开关会通过 ci/scripts/python_build.sh 中的PYARROW_WITH_*系列变量继续传递给 pyarrow 的构建（如PYARROW_WITH_PARQUET=${ARROW_PARQUET:-OFF}、PYARROW_WITH_DATASET=${ARROW_DATASET:-ON}）。

2.3 内存池与压缩编解码器

2.4 性能与调试

2.5 运行时路径

三、hooks.sh：hook 函数的设计与实现

hooks.sh 末尾的"$@"使脚本可以直接以source dev/conbench_envs/hooks.sh <函数名>的方式按名调用任意函数，这是其作为"函数注册表"的入口约定。

3.1 conda 环境相关 hook

create_conda_env_for_benchmark_build() { conda create -y -n "${BENCHMARKABLE_TYPE}" -c conda-forge \ --file ci/conda_env_unix.txt \ --file ci/conda_env_cpp.txt \ --file ci/conda_env_python.txt \ --file ci/conda_env_gandiva.txt \ compilers \ python="${PYTHON_VERSION}" \ pandas \ aws-sdk-cpp \ r }

该函数以ci/下的四个依赖清单文件为基底创建 conda 环境（环境名取自BENCHMARKABLE_TYPE）：

• ci/conda_env_unix.txt：Unix 通用依赖（autoconf、ccache、orc、pkg-config）；
• ci/conda_env_cpp.txt：C++ 构建依赖，含benchmark>=1.6.0,!=1.8.4（Google Benchmark）、boost-cpp、aws-sdk-cpp、thrift-cpp、orc、re2、snappy、zstd、xsimd等；
• ci/conda_env_python.txt：Python 依赖，含cython>=0.29.31、numpy>=1.16.6、pytest、s3fs等；
• ci/conda_env_gandiva.txt：Gandiva 所需clang>=11、llvmdev>=11。

activate_conda_env_for_benchmark_build()负责conda init bash并激活该环境，install_arrow_python_dependencies()通过pip install -r python/requirements-build.txt -r python/requirements-test.txt补齐 Python 侧依赖。

3.2 构建 hook

• build_arrow_cpp()：使用uuidgen生成随机构建目录，调用 ci/scripts/cpp_build.sh 执行完整 CMake + Ninja 构建并install到ARROW_HOME，同时优雅忽略 "Can't create temporary cache file" 的 ccache 报错；
• build_arrow_python()：调用 ci/scripts/python_build.sh，以--no-deps --no-build-isolation方式安装 pyarrow，并把ARROW_*变量映射为PYARROW_WITH_*（如PYARROW_WITH_PARQUET、PYARROW_WITH_ORC、PYARROW_WITH_S3）；
• build_arrow_r()：将 ci/etc/rprofile 追加到 R 的Rprofile.site，执行 ci/scripts/r_deps.sh 安装 R 依赖，再R CMD INSTALL安装 r 包；
• build_arrow_java()：调用 ci/scripts/java_build.sh 构建 Java 端；
• install_archery()：pip install -e dev/archery安装 Arrow 的开发者工具链 archery，cpp-micro基准依赖它定位构建产物；
• install_java_script_project_dependencies()：在js/下执行yarn安装 JavaScript 依赖。

3.3 组合 hook：一键构建 C++ + Python

create_conda_env_with_arrow_python()是面向"Python 基准"的高层封装，按顺序执行：

create_conda_env_for_benchmark_build → activate_conda_env_for_benchmark_build → install_arrow_python_dependencies → set_arrow_build_and_run_env_vars → build_arrow_cpp → build_arrow_python

四、从零搭建基准环境的 14 步实操

以下步骤来自 README，展示@ursabot基准构建在 Ubuntu 上如何组合benchmarks.env与hooks.sh。请根据自身操作系统与网络环境调整包管理器与版本。

步骤 1：安装 Arrow C++ 系统依赖

sudo su apt-get update -y -q && \ apt-get install -y -q --no-install-recommends \ autoconf ca-certificates ccache cmake g++ gcc gdb git \ libbenchmark-dev libboost-filesystem-dev libboost-regex-dev libboost-system-dev \ libbrotli-dev libbz2-dev libgflags-dev libcurl4-openssl-dev libgoogle-glog-dev \ liblz4-dev libprotobuf-dev libprotoc-dev libre2-dev libsnappy-dev libssl-dev \ libthrift-dev libutf8proc-dev libzstd-dev make ninja-build pkg-config \ protobuf-compiler rapidjson-dev tzdata wget && \ apt-get clean && rm -rf /var/lib/apt/lists* apt-get update -y -q && \ apt-get install -y -q python3 python3-pip python3-dev && \ apt-get clean && rm -rf /var/lib/apt/lists/*

这些库与 ci/conda_env_cpp.txt 声明的能力一一对应（brotli/bz2/lz4/snappy/zstd 压缩、boost、thrift、re2、protobuf 等），是ARROW_DEPENDENCY_SOURCE=AUTO下优先复用的系统依赖。

步骤 2：安装 Java 依赖

sudo su apt-get install openjdk-8-jdk apt-get install maven

验证最低版本（java、javac需 1.8+，Maven 需 3.x）：

# java -version openjdk version "1.8.0_292" # javac -version javac 1.8.0_292 # mvn -version Apache Maven 3.6.3

步骤 3：安装 JavaScript 依赖

sudo apt update && sudo apt -y upgrade && sudo apt update sudo apt -y install curl dirmngr apt-transport-https lsb-release ca-certificates curl -fsSL https://deb.nodesource.com/setup_14.x | sudo -E bash - sudo apt-get install -y nodejs sudo apt -y install yarn gcc g++ make

验证最低版本（Node 14+、Yarn 1.22+）：

# node --version v14.17.2 # yarn --version 1.22.5

步骤 4：安装 Miniconda

sudo apt install curl curl -LO https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh sudo bash Miniconda3-latest-Linux-x86_64.sh

步骤 5：设置环境变量

export ARROW_REPO=https://github.com/apache/arrow.git export BENCHMARKABLE=e6e9e6ea52b7a8f2682ffc4160168c936ca1d3e6 export BENCHMARKABLE_TYPE=arrow-commit export PYTHON_VERSION=3.8 export CONBENCH_EMAIL=... export CONBENCH_URL="https://conbench.ursa.dev" export CONBENCH_PASSWORD=... export MACHINE=...

• ARROW_REPO：Arrow 仓库克隆地址（可替换为你的 fork）；
• BENCHMARKABLE：待评测的 commit SHA，BENCHMARKABLE_TYPE同时用作 conda 环境名；
• PYTHON_VERSION：conda 环境中的 Python 版本，会传入create_conda_env_for_benchmark_build的python="${PYTHON_VERSION}"；
• CONBENCH_URL/CONBENCH_EMAIL/CONBENCH_PASSWORD：conbench 服务的端点与凭据；
• MACHINE：当前运行机器的 hostname，作为基准结果中的环境标识。

步骤 6：用组合 hook 构建 C++ 与 Python

git clone "${ARROW_REPO}" pushd arrow git fetch -v --prune -- origin "${BENCHMARKABLE}" git checkout -f "${BENCHMARKABLE}" source dev/conbench_envs/hooks.sh create_conda_env_with_arrow_python popd

该步骤等价于手动执行 3.3 节的全部子函数，最终在$CONDA_PREFIX中安装好 Arrow C++ 库与 pyarrow。

步骤 7：安装 conbench CLI

git clone https://github.com/ursacomputing/conbench.git pushd conbench pip install -r requirements-cli.txt pip install -U PyYAML python setup.py install popd

步骤 8：安装 benchmarks 基准仓库

git clone https://github.com/ursacomputing/benchmarks.git pushd benchmarks python setup.py develop popd

benchmarks仓库提供conbench各基准子命令的实现（如file-read、cpp-micro、dataframe-to-table、java-micro、js-micro）。

步骤 9：配置 conbench 凭据

pushd benchmarks touch .conbench echo "url: $CONBENCH_URL" >> .conbench echo "email: $CONBENCH_EMAIL" >> .conbench echo "password: $CONBENCH_PASSWORD" >> .conbench echo "host_name: $MACHINE" >> .conbench popd

.conbench是 conbench CLI 的本地凭据文件，运行基准时读取它向服务端上报结果。

步骤 10：运行 Python 基准

cd benchmarks conbench file-read ALL --iterations=3 --all=true --drop-caches=true

file-read遍历 ALL 数据集，--iterations=3控制重复次数，--drop-caches=true在每次迭代前清空系统页缓存以获得更稳定的 I/O 读数。

步骤 11：安装 archery 并运行 C++ 基准

pushd arrow source dev/conbench_envs/hooks.sh install_archery popd cd benchmarks conbench cpp-micro --iterations=1

install_archery以可编辑模式安装 dev/archery，cpp-micro会调用 archery 定位 cpp_build.sh 产出的 Google Benchmark 可执行文件（对应ARROW_BUILD_BENCHMARKS=ON）。

步骤 12：构建 R 并运行 R 基准

pushd arrow source dev/conbench_envs/hooks.sh build_arrow_r popd R -e "remotes::install_github('ursacomputing/arrowbench')" cd benchmarks conbench dataframe-to-table ALL --iterations=3 --drop-caches=true --language=R

build_arrow_r内部依赖 ci/scripts/r_deps.sh 处理 R 包的编译依赖，随后通过R CMD INSTALL安装 arrow R 包。

步骤 13：构建 Java 并运行 Java 基准

pushd arrow source dev/conbench_envs/hooks.sh build_arrow_java source dev/conbench_envs/hooks.sh install_archery popd cd benchmarks conbench java-micro --iterations=1

build_arrow_java调用 ci/scripts/java_build.sh 编译 Java 模块，之后可直接执行java-micro。

步骤 14：安装 JavaScript 依赖并运行 JS 基准

pushd arrow source dev/conbench_envs/hooks.sh install_java_script_project_dependencies popd cd benchmarks conbench js-micro

五、复用约定：其他仓库与服务的接入准则

benchmarks.env与hooks.sh对其他仓库和服务开放使用，但需遵守以下约束，保证与@ursabot基准构建的兼容性：

1. 不得删除或重命名已有 hook；
2. 既有 hook 的函数定义只能在 Arrow 的 commit 中更新，且仅当该 commit 内 Arrow 构建脚本或依赖文件发生重命名、移动或新增时；
3. 函数定义更新后，必须通过@ursabot please benchmark触发一次真实基准构建，确认更新没有破坏构建流程。

这一约定确保了 hook 契约的稳定性——任何外部服务都可以安全地依赖hooks.sh的函数名与语义。

六、从源码结构看设计要点

• 配置与脚本分离：benchmarks.env 只声明参数，hooks.sh 只定义流程，二者通过source组合，便于贡献者在 PR 中单独调整某一维度；
• 复用既有 CI 资产：所有 hook 均直接调用ci/scripts/下已在日常 CI 中验证的构建脚本（cpp_build.sh、python_build.sh、r_deps.sh、java_build.sh），避免了基准环境与发布环境行为漂移；
• 与 commit 绑定：hook 随被测 commit 一起检出，保证"测的是什么代码，就用什么环境声明"，是复现性能回归、评估构建参数影响的可信基础。

结语

通过dev/conbench_envs的benchmarks.env与hooks.sh，Apache Arrow 将跨语言基准测试的环境声明、构建流程与 PR 自动化（@ursabot please benchmark）完整地固化在版本库中。无论是想在本地复现官方基准、评估某个 CMake 选项对性能的影响，还是为其他项目搭建同构的 conbench 环境，都可以以上述 14 步流程为起点，并以benchmarks.env的参数表与hooks.sh的函数清单为对照手册进行定制。

• 数据工程
• 大数据
• 序列化
• 数据分析