Apache Arrow 开发者利器用 Archery 统一日常构建、基准测试与持续集成工作流【免费下载链接】arrowApache Arrow is the universal columnar format and multi-language toolbox for fast data interchange and in-memory analytics项目地址: https://gitcode.com/GitHub_Trending/arrow3/arrowApache Arrow 仓库规模庞大C、Java、Python、R、Ruby 等多个语言实现并存日常开发中构建、测试、基准对比与 CI 调度高度重复。Archery 是 Arrow 官方为开发者打造的 Python 命令行工具把初始化 C 构建、运行基准测试、调度 Docker Compose 构建、执行跨语言集成测试等任务统一封装为独立子命令。读完本文你将掌握 Archery 的安装方式、全部子命令的能力边界以及如何用它替代手工 CMake 命令与 docker compose 操作显著提升 Arrow 源码树的日常开发效率。Archery 是什么Arrow 开发者工具箱Archery 是一个纯 Python 编写的命令行实用程序源码位于 dev/archery在 官方文档 中被定位为为了简化日常开发任务而开发的工具To ease some of the daily development tasks, we developed a Python-written utility called Archery。它的入口实现位于 dev/archery/archery/cli.py通过setup.py中的entry_points注册为archeryarchery.cli:archery控制台命令见 dev/archery/setup.py。从源码结构看Archery 采用一个根命令 多个独立子命令的架构根命令archery负责全局选项与日志配置具体功能全部委托给benchmark、build、docker、integration、linking、lint、numpydoc、release、crossbow、ci等子命令模块。其中docker、release、crossbow、ci是通过add_optional_command按需挂载的见 cli.py这与 README 中Archery 由若干子包组成按需安装的设计保持一致见 dev/archery/README.md。安装 Archeryeditable 模式与按需子包环境要求Archery 要求Python 3.11 或更高版本。setup.py中同时通过sys.version_info (3, 11)和python_requires3.11双重校验了 Python 版本见 dev/archery/setup.py。推荐安装方式官方文档推荐使用editable-e模式安装这样每次拉取 Arrow 仓库更新后安装会自动跟随最新代码无需重复安装。克隆 Arrow 仓库后在仓库顶层目录执行$ pip install -e dev/archery[all][all]是全部可选子包的别名。Archery 按功能拆分了多个 extras依赖定义见 dev/archery/setup.py子包extras对应功能额外依赖lint代码检查与部分自动格式化基础依赖benchmark运行 Arrow 基准测试pandasdocker简化 docker compose 任务ruamel.yaml、python-dotenvrelease发布相关辅助命令pygithub2.9.0、jinja2、semver、gitpythoncrossbow触发并交互 Crossbow 构建系统jinja2、pygit21.14.0、pygithub2.5.0、requests、ruamel.yamlintegration集成测试支持cffi、numpyJava 侧另需integration-java→jpype1numpydocNumpyDoc 文档字符串检查numpydoc1.1.0bot评论机器人crossbow 依赖 pygithub2.9.0如果只想用其中一部分功能可以按需安装例如$ pip install -e dev/archery[lint] $ pip install -e dev/archery[benchmark] $ pip install -e dev/archery[docker] $ pip install -e dev/archery[crossbow]依赖的第三方工具Archery 的许多操作会调用Docker与Docker Compose官方文档明确说明Many operations in Archery make use of Docker and Docker Compose因此建议在安装 Archery 之外另行安装这两个工具。Archery 在解析镜像时优先使用docker compose内置子命令也支持通过ARCHERY_USE_LEGACY_DOCKER_COMPOSE等环境变量回退到独立的docker-compose工具见 dev/archery/archery/docker/cli.py。全局用法与子命令一览查看帮助Archery 的所有子命令都基于 Click 框架实现根命令装饰器位于 cli.py因此--help输出非常规范。运行$ archery --help Usage: archery [OPTIONS] COMMAND [ARGS]... Apache Arrow developer utilities. See sub-commands help with archery cmd --help. Options: --debug Increase logging with debugging output. --pdb Invoke pdb on uncaught exception. -q, --quiet Silence executed commands. --help Show this message and exit. Commands: benchmark Arrow benchmarking. build Initialize an Arrow C build crossbow Schedule packaging tasks or nightly builds on CI services. docker Interact with Docker Compose based builds. integration Execute protocol and Flight integration tests linking Quick and dirty utilities for checking library linkage. lint Check Arrow source tree for errors numpydoc Lint python docstring with NumpyDoc release Release related commands. trigger-bot全局选项解析对照 cli.py 的实现全局选项的含义如下--debug将日志级别提升到 DEBUG输出更多调试信息同时会向 docker build 传递--progressplain。该选项可通过环境变量ARCHERY_DEBUG开启。--pdb在未捕获异常时进入pdb调试器实现为替换sys.excepthook。-q, --quiet静默执行命令抑制输出。-h, --help显示帮助help_option_names同时接受-h与--help。每个子命令都有独立的帮助输出例如$ archery docker --help Usage: archery docker [OPTIONS] COMMAND [ARGS]... Interact with Docker Compose based builds. Options: --src arrow_src Specify Arrow source directory. --help Show this message and exit. Commands: images List the available Docker Compose images. push Push the generated Docker Compose image. run Execute Docker Compose builds.子命令与源码模块对应关系子命令功能主要实现build初始化 Arrow C 构建目录cli.pybenchmark基准测试list / run / diffbenchmark/dockerDocker Compose 构建交互docker/integration协议与 Flight 集成测试integration/linking动态库链接依赖检查linking.pynumpydocNumpyDoc 风格 docstring 检查utils/lint.pyrelease发布相关命令release/crossbow打包任务 / 夜间构建调度crossbow/ciCI 相关辅助命令ci/trigger-bot响应 GitHub 评论与 PR 事件bot.pybuild一行命令初始化 Arrow C 构建archery build的核心价值是把 CMake 配置参数收敛为统一的 CLI 参数避免手工记忆几十个-DARROW_*开关。其实现流程见 cli.py为将 CLI 参数封装为CppConfiguration定义于 lang/cpp.py结合--src指定的 Arrow 源码目录构造CppCMakeDefinition生成/复用构建目录已有目录默认不覆盖需--force删除可选地通过--targets调用生成器执行目标如--targetsall --targetstest。基本用法# 在目录 clang8-build 中初始化 clang8 avx2 构建 $ archery build --ccclang-8 --cxxclang-8 --cxx-flags-mavx2 clang8-build # 构建并运行测试 $ archery build --targetsall --targetstest build主要选项对照 cli.py工具链--cc/--cxx指定编译器--cxx-flags追加 C 编译标志--cpp-package-prefix对应ARROW_PACKAGE_PREFIX并启用ARROW_DEPENDENCY_SOURCESYSTEM。构建类型--build-type取值debug/relwithdebinfo/release--build-static/--build-shared/--build-unity控制静态库、共享库与 unity build。告警级别--warn-level取值everything/checkin/production控制-W(no-)error。SIMD--simd-level取值NONE/SSE4_2/AVX2/AVX512对应ARROW_SIMD_LEVEL。测试与基准--with-tests、--with-benchmarks、--with-examples、--with-integration。Sanitizer--use-asan、--use-tsan、--use-ubsan、--with-fuzzing。功能模块--with-compute、--with-csv、--with-dataset、--with-filesystem、--with-flight、--with-gandiva、--with-gcs、--with-hdfs、--with-hiveserver2、--with-ipc、--with-json、--with-mimalloc、--with-parquet、--with-python、--with-r、--with-s3、--with-cuda等逐一映射到同名ARROW_*CMake 选项。注意--with-r并非 CMake 选项而是联动切换所需的其他选项。压缩库--with-brotli、--with-bz2、--with-lz4、--with-snappy、--with-zlib、--with-zstd。透传与杂项--cmake-extras可叠加透传给 cmake、--install-prefix对应CMAKE_INSTALL_PREFIX默认取$CONDA_PREFIX、-f/--force删除已有构建目录、--targets可叠加的生成目标。从源码结构看该命令会完整继承调用者的环境变量且不会改动已存在的构建目录只有显式传入--force才会删除重建——这与build命令的 docstring 描述一致见 cli.py。benchmark基准测试的三段式工作流benchmark子命令组见 cli.py支持 C 与 Java 两种语言包含三个子命令archery benchmark list列出基准测试套件。archery benchmark run针对单个构建/版本运行完整基准套件可输出 JSON 结果。archery benchmark diff像git diff一样对比两次基准运行输出回归报告。目标指定git 版本或构建目录三个子命令都接受一个rev_or_path参数取值可以是 git 提交/标签/特殊值如HEAD、HEAD~1也可以是已有的 CMake 构建目录。特殊标记WORKSPACE表示当前 git 工作区不做 clone。当引用 commit 时Archery 会在临时目录中克隆--src指定的 Arrow 源码并检出对应分支可用--preserve保留该临时工作区供排查。常用示例# 在当前工作区运行基准 $ archery benchmark run # 对比当前工作区与主干分支contender 默认 WORKSPACEbaseline 默认 origin/HEAD $ archery benchmark diff # 对比两个构建目录例如 gcc-7 与 clang-8 的编译产物 $ archery build --with-benchmarkstrue --ccgcc-7 --cxxg-7 gcc7-build $ archery build --with-benchmarkstrue --ccclang-8 --cxxclang-8 clang8-build $ archery benchmark diff gcc7-build clang8-build # 限定测试范围只测聚合套件中的 Sum/Mean Kernel $ archery benchmark diff --suite-filter^arrow-compute-aggregate \ --benchmark-filter(Sum|Mean)Kernel # 结果落盘 $ archery benchmark run --outputrun.json $ archery benchmark diff --outputresult.json关键参数--threshold回归失败阈值百分比默认值来自benchmark.compare.DEFAULT_THRESHOLD见 cli.py。--repetitions每个基准的重复次数C 默认 1Java 默认 5--repetition-min-time可设置单次最小时长目前仅 C 支持。--suite-filter/--benchmark-filter用正则过滤套件与基准。--no-counters隐藏 diff 报告中的 counters 字段Java 报告中该字段会重命名为 configurations。--preserve/--preserve-dir保留临时工作区。--languagecpp或java其他值会被拒绝。Java 相关--java-home、--java-options、--build-extras、--benchmark-extras透传给 mvn。diff 报告的格式化逻辑位于 cli.py结果先序列化为 JSON Lines再用 pandas 解析出change %列并排序最终分成 Non-regressions 与 Regressions 两个区块输出。测试用例可见 dev/archery/archery/tests/test_benchmarks.py 及其 fixtures如archery-benchmark-diff.jsonl。docker基于 Docker Compose 的构建调度Archery 的 docker 子命令是官方文档中篇幅最大的部分完整的 Docker 使用指南见 Running Docker Builds。核心思路是Arrow 的大部分 Linux CI 任务通过 Docker Compose 解耦保持 CI 配置最小化从而让本地可复现 CI 环境成为可能。基本操作# 列出可用的 Compose 镜像来源于 compose.yaml 的 x-hierarchy 定义 $ archery docker images # 执行一个构建 $ archery docker run conda-pythonarchery docker run conda-python等价于依次执行$ docker compose pull --ignore-pull-failures conda-cpp $ docker compose pull --ignore-pull-failures conda-python $ docker compose build conda-cpp $ docker compose build conda-python $ docker compose run --rm conda-python之所以会先构建父镜像conda-cpp再构建conda-python是因为 Compose 配置采用**层级镜像hierarchical images**设计多个语言绑定GLib、Ruby、R、Python共享同一个 C 基础镜像避免在多个 Dockerfile 中重复定义 C 环境见 docker.rst。镜像间的依赖关系记录在仓库根目录 compose.yaml 的x-hierarchy字段中由 docker/core.py 的flatten()解析为构建顺序。高级用法只显示命令而不执行--dry-run会 mock 掉实际的 docker 调用仅回显命令$ archery docker --dry-run run conda-python禁用镜像拉取 / 禁用缓存$ archery docker run --no-cache conda-python对应命令为docker compose build --no-cache conda-cppdocker compose build --no-cache conda-pythondocker compose run --rm conda-python。只禁用叶子镜像的缓存常用于强制构建依赖的开发版本如 pandas 上游分支$ PANDASupstream_devel archery docker run --no-leaf-cache conda-python-pandas这会构建conda-cpp conda-python conda-python-pandas分支其中仅叶子镜像conda-python-pandas使用--no-cache且不拉取该叶子镜像详见 docker.rst。PANDAS属于 Docker 构建参数默认值存放在顶层.env文件中ComposeConfig._read_env()见 docker/core.py会读取.env、合并进程环境变量并把ARCH翻译为ARCH_ALIAS/ARCH_SHORT供 Dockerfile 使用。跳过 pull/build 阶段当镜像已构建但 compose 的层缓存失效时可省去重复构建$ archery docker run --no-pull --no-build conda-python向容器传递环境变量-e/--env用法与docker run一致容器内的构建脚本大多支持通过环境变量配置例如 C 构建参数可参考 ci/scripts/cpp_build.sh$ archery docker run --env CMAKE_BUILD_TYPErelease ubuntu-cpp以自定义命令进入容器交互式调试$ archery docker run ubuntu-cpp bash增加调试输出archery --debug docker run ubuntu-cpp除开启 DEBUG 日志外还会给 docker build 追加--progressplain。GPU / 资源限制 / 卷挂载run还支持--gpus当 service 在x-with-gpus中声明时自动追加--gpus all、--resource-limit模拟 GitHub Actions 之类的 CI 环境 CPU/内存限制此时强制使用--using-docker-cli、-v/--volume见 docker/cli.py 与 docker/core.py。其他 docker 子命令命令说明archery docker images列出可用镜像来自x-hierarchy的键见 core.pyarchery docker build仅执行构建--no-cache控制祖先镜像缓存--no-leaf-cache只禁用叶子缓存archery docker pull仅拉取镜像--pull-leaf/--no-leaf控制是否拉取叶子镜像archery docker push推送镜像-u/-p或环境变量ARCHERY_DOCKER_USER/ARCHERY_DOCKER_PASSWORD登录仓库archery docker info查看某 service 的 Compose 定义可用-s只显示指定 key如 command / environment / build / dockerfilearchery docker check-config校验 Compose 配置卷缓存与镜像层级大部分 Compose 容器会将宿主机目录挂载进容器以复用ccache与 Maven 制品缓存这些 docker volume 位于仓库根目录的.docker目录下清理缓存只需删除相应目录或整个.docker目录见 docker.rst。新增镜像时Compose 配置文件中的内联注释compose.yaml提供了逐步指引。integration跨语言协议与 Flight 集成测试archery integration负责执行 IPC、Flight、C Data Interface 三类跨语言集成测试见 cli.py支持的实现包括 C、Java、JavaScript、Go、Rust、Ruby、.NET、nanoarrow。关键选项--with-cpp/--with-java/--with-js/--with-go/--with-rust/--with-ruby/--with-dotnet/--with-nanoarrow/--with-all启用参与测试的实现也可通过ARCHERY_INTEGRATION_WITH_*环境变量设置。--target-implementations精确指定参与测试的实现列表或用ARCHERY_INTEGRATION_TARGET_IMPLEMENTATIONS用于缩小测试矩阵、缩短 CI 时间。--run-ipc/--run-flight/--run-c-data选择要运行的协议至少启用一种。--random-seed数据生成 PRNG 种子默认 12345保证测试数据可复现。-x/--stop-on-error遇错即停--serial串行执行-k/--match按子串过滤测试名。--write-generated-json/--write-gold-files生成测试数据或 gold 文件。从源码 docstring 看当同时指定--with-cpp、--with-java、--with-rust时会生成全部 9 种 Producer×Consumer 组合而指定--target-implementationscpp,java时只生成 Rust 作为第三方的组合见 cli.py。各语言的测试适配器位于 dev/archery/archery/integration/tester_*.py数据生成逻辑在 datagen.py。linking 与 numpydoc链接检查与文档规范archery linking check-dependencies检查动态库的链接依赖-a/--allow与-d/--disallow分别声明允许/禁止链接的库白名单与黑名单用于防止意外引入运行时依赖实现见 linking.py。archery numpydoc校验 pyarrow 模块的 docstring 是否符合 NumpyDoc 规范。默认校验 pyarrow 全部模块可传模块或符号缩小范围如archery numpydoc pyarrow.dataset、archery numpydoc pyarrow.csv pyarrow.json pyarrow.parquet-a/--allow-rule与-d/--disallow-rule控制启用/禁用的规则默认禁用{GL01, SA01, EX01, ES01}四类见 cli.py。校验失败时进程以退出码 1 结束便于接入 CI。trigger-bot 与其他开发辅助archery trigger-bot用于在 CI 中响应 Arrow 仓库的 GitHub 评论与 PR 事件评论类事件由CommentBot处理PR 工作流事件由PullRequestWorkflowBot处理--event-name/--event-payload传入事件名与 JSON payloadtoken 通过GH_TOKEN或ARROW_GITHUB_TOKEN提供见 cli.py。机器人逻辑与对应测试位于 bot.py 和 dev/archery/archery/tests/test_bot.py。此外crossbow打包任务与夜间构建调度、release发布辅助与ci子命令也随[all]安装启用其中 crossbow 的完整用法可参考 crossbow 文档。深入阅读指引官方开发者文档archery.rst、docker.rst、crossbow.rst工具源码dev/archery入口 cli.py、Docker 实现 docker/core.py、依赖声明 setup.py测试用例dev/archery/archery/tests、dev/archery/archery/docker/tests、dev/archery/archery/crossbow/tests可从中了解各子命令的预期行为与 fixtures实际 Docker 镜像定义compose.yaml含x-hierarchy、x-limit-presets、x-with-gpus等扩展字段与仓库根目录 .env总而言之Archery 把 Arrow 仓库构建 - 测试 - 基准 - 集成 - 发布的完整开发链路收敛到了一组统一、可脚本化、可复现的命令上日常用archery build替代手写 CMake用archery benchmark diff做回归检测用archery docker run在本地复现 CI 环境。掌握它是高效参与 Arrow 开发的第一步。【免费下载链接】arrowApache Arrow is the universal columnar format and multi-language toolbox for fast data interchange and in-memory analytics项目地址: https://gitcode.com/GitHub_Trending/arrow3/arrow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Apache Arrow 开发者利器：用 Archery 统一日常构建、基准测试与持续集成工作流
Apache Arrow 开发者利器用 Archery 统一日常构建、基准测试与持续集成工作流【免费下载链接】arrowApache Arrow is the universal columnar format and multi-language toolbox for fast data interchange and in-memory analytics项目地址: https://gitcode.com/GitHub_Trending/arrow3/arrowApache Arrow 仓库规模庞大C、Java、Python、R、Ruby 等多个语言实现并存日常开发中构建、测试、基准对比与 CI 调度高度重复。Archery 是 Arrow 官方为开发者打造的 Python 命令行工具把初始化 C 构建、运行基准测试、调度 Docker Compose 构建、执行跨语言集成测试等任务统一封装为独立子命令。读完本文你将掌握 Archery 的安装方式、全部子命令的能力边界以及如何用它替代手工 CMake 命令与 docker compose 操作显著提升 Arrow 源码树的日常开发效率。Archery 是什么Arrow 开发者工具箱Archery 是一个纯 Python 编写的命令行实用程序源码位于 dev/archery在 官方文档 中被定位为为了简化日常开发任务而开发的工具To ease some of the daily development tasks, we developed a Python-written utility called Archery。它的入口实现位于 dev/archery/archery/cli.py通过setup.py中的entry_points注册为archeryarchery.cli:archery控制台命令见 dev/archery/setup.py。从源码结构看Archery 采用一个根命令 多个独立子命令的架构根命令archery负责全局选项与日志配置具体功能全部委托给benchmark、build、docker、integration、linking、lint、numpydoc、release、crossbow、ci等子命令模块。其中docker、release、crossbow、ci是通过add_optional_command按需挂载的见 cli.py这与 README 中Archery 由若干子包组成按需安装的设计保持一致见 dev/archery/README.md。安装 Archeryeditable 模式与按需子包环境要求Archery 要求Python 3.11 或更高版本。setup.py中同时通过sys.version_info (3, 11)和python_requires3.11双重校验了 Python 版本见 dev/archery/setup.py。推荐安装方式官方文档推荐使用editable-e模式安装这样每次拉取 Arrow 仓库更新后安装会自动跟随最新代码无需重复安装。克隆 Arrow 仓库后在仓库顶层目录执行$ pip install -e dev/archery[all][all]是全部可选子包的别名。Archery 按功能拆分了多个 extras依赖定义见 dev/archery/setup.py子包extras对应功能额外依赖lint代码检查与部分自动格式化基础依赖benchmark运行 Arrow 基准测试pandasdocker简化 docker compose 任务ruamel.yaml、python-dotenvrelease发布相关辅助命令pygithub2.9.0、jinja2、semver、gitpythoncrossbow触发并交互 Crossbow 构建系统jinja2、pygit21.14.0、pygithub2.5.0、requests、ruamel.yamlintegration集成测试支持cffi、numpyJava 侧另需integration-java→jpype1numpydocNumpyDoc 文档字符串检查numpydoc1.1.0bot评论机器人crossbow 依赖 pygithub2.9.0如果只想用其中一部分功能可以按需安装例如$ pip install -e dev/archery[lint] $ pip install -e dev/archery[benchmark] $ pip install -e dev/archery[docker] $ pip install -e dev/archery[crossbow]依赖的第三方工具Archery 的许多操作会调用Docker与Docker Compose官方文档明确说明Many operations in Archery make use of Docker and Docker Compose因此建议在安装 Archery 之外另行安装这两个工具。Archery 在解析镜像时优先使用docker compose内置子命令也支持通过ARCHERY_USE_LEGACY_DOCKER_COMPOSE等环境变量回退到独立的docker-compose工具见 dev/archery/archery/docker/cli.py。全局用法与子命令一览查看帮助Archery 的所有子命令都基于 Click 框架实现根命令装饰器位于 cli.py因此--help输出非常规范。运行$ archery --help Usage: archery [OPTIONS] COMMAND [ARGS]... Apache Arrow developer utilities. See sub-commands help with archery cmd --help. Options: --debug Increase logging with debugging output. --pdb Invoke pdb on uncaught exception. -q, --quiet Silence executed commands. --help Show this message and exit. Commands: benchmark Arrow benchmarking. build Initialize an Arrow C build crossbow Schedule packaging tasks or nightly builds on CI services. docker Interact with Docker Compose based builds. integration Execute protocol and Flight integration tests linking Quick and dirty utilities for checking library linkage. lint Check Arrow source tree for errors numpydoc Lint python docstring with NumpyDoc release Release related commands. trigger-bot全局选项解析对照 cli.py 的实现全局选项的含义如下--debug将日志级别提升到 DEBUG输出更多调试信息同时会向 docker build 传递--progressplain。该选项可通过环境变量ARCHERY_DEBUG开启。--pdb在未捕获异常时进入pdb调试器实现为替换sys.excepthook。-q, --quiet静默执行命令抑制输出。-h, --help显示帮助help_option_names同时接受-h与--help。每个子命令都有独立的帮助输出例如$ archery docker --help Usage: archery docker [OPTIONS] COMMAND [ARGS]... Interact with Docker Compose based builds. Options: --src arrow_src Specify Arrow source directory. --help Show this message and exit. Commands: images List the available Docker Compose images. push Push the generated Docker Compose image. run Execute Docker Compose builds.子命令与源码模块对应关系子命令功能主要实现build初始化 Arrow C 构建目录cli.pybenchmark基准测试list / run / diffbenchmark/dockerDocker Compose 构建交互docker/integration协议与 Flight 集成测试integration/linking动态库链接依赖检查linking.pynumpydocNumpyDoc 风格 docstring 检查utils/lint.pyrelease发布相关命令release/crossbow打包任务 / 夜间构建调度crossbow/ciCI 相关辅助命令ci/trigger-bot响应 GitHub 评论与 PR 事件bot.pybuild一行命令初始化 Arrow C 构建archery build的核心价值是把 CMake 配置参数收敛为统一的 CLI 参数避免手工记忆几十个-DARROW_*开关。其实现流程见 cli.py为将 CLI 参数封装为CppConfiguration定义于 lang/cpp.py结合--src指定的 Arrow 源码目录构造CppCMakeDefinition生成/复用构建目录已有目录默认不覆盖需--force删除可选地通过--targets调用生成器执行目标如--targetsall --targetstest。基本用法# 在目录 clang8-build 中初始化 clang8 avx2 构建 $ archery build --ccclang-8 --cxxclang-8 --cxx-flags-mavx2 clang8-build # 构建并运行测试 $ archery build --targetsall --targetstest build主要选项对照 cli.py工具链--cc/--cxx指定编译器--cxx-flags追加 C 编译标志--cpp-package-prefix对应ARROW_PACKAGE_PREFIX并启用ARROW_DEPENDENCY_SOURCESYSTEM。构建类型--build-type取值debug/relwithdebinfo/release--build-static/--build-shared/--build-unity控制静态库、共享库与 unity build。告警级别--warn-level取值everything/checkin/production控制-W(no-)error。SIMD--simd-level取值NONE/SSE4_2/AVX2/AVX512对应ARROW_SIMD_LEVEL。测试与基准--with-tests、--with-benchmarks、--with-examples、--with-integration。Sanitizer--use-asan、--use-tsan、--use-ubsan、--with-fuzzing。功能模块--with-compute、--with-csv、--with-dataset、--with-filesystem、--with-flight、--with-gandiva、--with-gcs、--with-hdfs、--with-hiveserver2、--with-ipc、--with-json、--with-mimalloc、--with-parquet、--with-python、--with-r、--with-s3、--with-cuda等逐一映射到同名ARROW_*CMake 选项。注意--with-r并非 CMake 选项而是联动切换所需的其他选项。压缩库--with-brotli、--with-bz2、--with-lz4、--with-snappy、--with-zlib、--with-zstd。透传与杂项--cmake-extras可叠加透传给 cmake、--install-prefix对应CMAKE_INSTALL_PREFIX默认取$CONDA_PREFIX、-f/--force删除已有构建目录、--targets可叠加的生成目标。从源码结构看该命令会完整继承调用者的环境变量且不会改动已存在的构建目录只有显式传入--force才会删除重建——这与build命令的 docstring 描述一致见 cli.py。benchmark基准测试的三段式工作流benchmark子命令组见 cli.py支持 C 与 Java 两种语言包含三个子命令archery benchmark list列出基准测试套件。archery benchmark run针对单个构建/版本运行完整基准套件可输出 JSON 结果。archery benchmark diff像git diff一样对比两次基准运行输出回归报告。目标指定git 版本或构建目录三个子命令都接受一个rev_or_path参数取值可以是 git 提交/标签/特殊值如HEAD、HEAD~1也可以是已有的 CMake 构建目录。特殊标记WORKSPACE表示当前 git 工作区不做 clone。当引用 commit 时Archery 会在临时目录中克隆--src指定的 Arrow 源码并检出对应分支可用--preserve保留该临时工作区供排查。常用示例# 在当前工作区运行基准 $ archery benchmark run # 对比当前工作区与主干分支contender 默认 WORKSPACEbaseline 默认 origin/HEAD $ archery benchmark diff # 对比两个构建目录例如 gcc-7 与 clang-8 的编译产物 $ archery build --with-benchmarkstrue --ccgcc-7 --cxxg-7 gcc7-build $ archery build --with-benchmarkstrue --ccclang-8 --cxxclang-8 clang8-build $ archery benchmark diff gcc7-build clang8-build # 限定测试范围只测聚合套件中的 Sum/Mean Kernel $ archery benchmark diff --suite-filter^arrow-compute-aggregate \ --benchmark-filter(Sum|Mean)Kernel # 结果落盘 $ archery benchmark run --outputrun.json $ archery benchmark diff --outputresult.json关键参数--threshold回归失败阈值百分比默认值来自benchmark.compare.DEFAULT_THRESHOLD见 cli.py。--repetitions每个基准的重复次数C 默认 1Java 默认 5--repetition-min-time可设置单次最小时长目前仅 C 支持。--suite-filter/--benchmark-filter用正则过滤套件与基准。--no-counters隐藏 diff 报告中的 counters 字段Java 报告中该字段会重命名为 configurations。--preserve/--preserve-dir保留临时工作区。--languagecpp或java其他值会被拒绝。Java 相关--java-home、--java-options、--build-extras、--benchmark-extras透传给 mvn。diff 报告的格式化逻辑位于 cli.py结果先序列化为 JSON Lines再用 pandas 解析出change %列并排序最终分成 Non-regressions 与 Regressions 两个区块输出。测试用例可见 dev/archery/archery/tests/test_benchmarks.py 及其 fixtures如archery-benchmark-diff.jsonl。docker基于 Docker Compose 的构建调度Archery 的 docker 子命令是官方文档中篇幅最大的部分完整的 Docker 使用指南见 Running Docker Builds。核心思路是Arrow 的大部分 Linux CI 任务通过 Docker Compose 解耦保持 CI 配置最小化从而让本地可复现 CI 环境成为可能。基本操作# 列出可用的 Compose 镜像来源于 compose.yaml 的 x-hierarchy 定义 $ archery docker images # 执行一个构建 $ archery docker run conda-pythonarchery docker run conda-python等价于依次执行$ docker compose pull --ignore-pull-failures conda-cpp $ docker compose pull --ignore-pull-failures conda-python $ docker compose build conda-cpp $ docker compose build conda-python $ docker compose run --rm conda-python之所以会先构建父镜像conda-cpp再构建conda-python是因为 Compose 配置采用**层级镜像hierarchical images**设计多个语言绑定GLib、Ruby、R、Python共享同一个 C 基础镜像避免在多个 Dockerfile 中重复定义 C 环境见 docker.rst。镜像间的依赖关系记录在仓库根目录 compose.yaml 的x-hierarchy字段中由 docker/core.py 的flatten()解析为构建顺序。高级用法只显示命令而不执行--dry-run会 mock 掉实际的 docker 调用仅回显命令$ archery docker --dry-run run conda-python禁用镜像拉取 / 禁用缓存$ archery docker run --no-cache conda-python对应命令为docker compose build --no-cache conda-cppdocker compose build --no-cache conda-pythondocker compose run --rm conda-python。只禁用叶子镜像的缓存常用于强制构建依赖的开发版本如 pandas 上游分支$ PANDASupstream_devel archery docker run --no-leaf-cache conda-python-pandas这会构建conda-cpp conda-python conda-python-pandas分支其中仅叶子镜像conda-python-pandas使用--no-cache且不拉取该叶子镜像详见 docker.rst。PANDAS属于 Docker 构建参数默认值存放在顶层.env文件中ComposeConfig._read_env()见 docker/core.py会读取.env、合并进程环境变量并把ARCH翻译为ARCH_ALIAS/ARCH_SHORT供 Dockerfile 使用。跳过 pull/build 阶段当镜像已构建但 compose 的层缓存失效时可省去重复构建$ archery docker run --no-pull --no-build conda-python向容器传递环境变量-e/--env用法与docker run一致容器内的构建脚本大多支持通过环境变量配置例如 C 构建参数可参考 ci/scripts/cpp_build.sh$ archery docker run --env CMAKE_BUILD_TYPErelease ubuntu-cpp以自定义命令进入容器交互式调试$ archery docker run ubuntu-cpp bash增加调试输出archery --debug docker run ubuntu-cpp除开启 DEBUG 日志外还会给 docker build 追加--progressplain。GPU / 资源限制 / 卷挂载run还支持--gpus当 service 在x-with-gpus中声明时自动追加--gpus all、--resource-limit模拟 GitHub Actions 之类的 CI 环境 CPU/内存限制此时强制使用--using-docker-cli、-v/--volume见 docker/cli.py 与 docker/core.py。其他 docker 子命令命令说明archery docker images列出可用镜像来自x-hierarchy的键见 core.pyarchery docker build仅执行构建--no-cache控制祖先镜像缓存--no-leaf-cache只禁用叶子缓存archery docker pull仅拉取镜像--pull-leaf/--no-leaf控制是否拉取叶子镜像archery docker push推送镜像-u/-p或环境变量ARCHERY_DOCKER_USER/ARCHERY_DOCKER_PASSWORD登录仓库archery docker info查看某 service 的 Compose 定义可用-s只显示指定 key如 command / environment / build / dockerfilearchery docker check-config校验 Compose 配置卷缓存与镜像层级大部分 Compose 容器会将宿主机目录挂载进容器以复用ccache与 Maven 制品缓存这些 docker volume 位于仓库根目录的.docker目录下清理缓存只需删除相应目录或整个.docker目录见 docker.rst。新增镜像时Compose 配置文件中的内联注释compose.yaml提供了逐步指引。integration跨语言协议与 Flight 集成测试archery integration负责执行 IPC、Flight、C Data Interface 三类跨语言集成测试见 cli.py支持的实现包括 C、Java、JavaScript、Go、Rust、Ruby、.NET、nanoarrow。关键选项--with-cpp/--with-java/--with-js/--with-go/--with-rust/--with-ruby/--with-dotnet/--with-nanoarrow/--with-all启用参与测试的实现也可通过ARCHERY_INTEGRATION_WITH_*环境变量设置。--target-implementations精确指定参与测试的实现列表或用ARCHERY_INTEGRATION_TARGET_IMPLEMENTATIONS用于缩小测试矩阵、缩短 CI 时间。--run-ipc/--run-flight/--run-c-data选择要运行的协议至少启用一种。--random-seed数据生成 PRNG 种子默认 12345保证测试数据可复现。-x/--stop-on-error遇错即停--serial串行执行-k/--match按子串过滤测试名。--write-generated-json/--write-gold-files生成测试数据或 gold 文件。从源码 docstring 看当同时指定--with-cpp、--with-java、--with-rust时会生成全部 9 种 Producer×Consumer 组合而指定--target-implementationscpp,java时只生成 Rust 作为第三方的组合见 cli.py。各语言的测试适配器位于 dev/archery/archery/integration/tester_*.py数据生成逻辑在 datagen.py。linking 与 numpydoc链接检查与文档规范archery linking check-dependencies检查动态库的链接依赖-a/--allow与-d/--disallow分别声明允许/禁止链接的库白名单与黑名单用于防止意外引入运行时依赖实现见 linking.py。archery numpydoc校验 pyarrow 模块的 docstring 是否符合 NumpyDoc 规范。默认校验 pyarrow 全部模块可传模块或符号缩小范围如archery numpydoc pyarrow.dataset、archery numpydoc pyarrow.csv pyarrow.json pyarrow.parquet-a/--allow-rule与-d/--disallow-rule控制启用/禁用的规则默认禁用{GL01, SA01, EX01, ES01}四类见 cli.py。校验失败时进程以退出码 1 结束便于接入 CI。trigger-bot 与其他开发辅助archery trigger-bot用于在 CI 中响应 Arrow 仓库的 GitHub 评论与 PR 事件评论类事件由CommentBot处理PR 工作流事件由PullRequestWorkflowBot处理--event-name/--event-payload传入事件名与 JSON payloadtoken 通过GH_TOKEN或ARROW_GITHUB_TOKEN提供见 cli.py。机器人逻辑与对应测试位于 bot.py 和 dev/archery/archery/tests/test_bot.py。此外crossbow打包任务与夜间构建调度、release发布辅助与ci子命令也随[all]安装启用其中 crossbow 的完整用法可参考 crossbow 文档。深入阅读指引官方开发者文档archery.rst、docker.rst、crossbow.rst工具源码dev/archery入口 cli.py、Docker 实现 docker/core.py、依赖声明 setup.py测试用例dev/archery/archery/tests、dev/archery/archery/docker/tests、dev/archery/archery/crossbow/tests可从中了解各子命令的预期行为与 fixtures实际 Docker 镜像定义compose.yaml含x-hierarchy、x-limit-presets、x-with-gpus等扩展字段与仓库根目录 .env总而言之Archery 把 Arrow 仓库构建 - 测试 - 基准 - 集成 - 发布的完整开发链路收敛到了一组统一、可脚本化、可复现的命令上日常用archery build替代手写 CMake用archery benchmark diff做回归检测用archery docker run在本地复现 CI 环境。掌握它是高效参与 Arrow 开发的第一步。【免费下载链接】arrowApache Arrow is the universal columnar format and multi-language toolbox for fast data interchange and in-memory analytics项目地址: https://gitcode.com/GitHub_Trending/arrow3/arrow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考