Apache Arrow 日常开发工具 Archery 完全指南：安装、命令与 Docker 工作流

Apache Arrow 日常开发工具 Archery 完全指南安装、命令与 Docker 工作流【免费下载链接】arrowApache Arrow is a multi-language toolbox for accelerated data interchange and in-memory processing项目地址: https://gitcode.com/gh_mirrors/arrow12/arrow本文以 Apache Arrow 仓库中的官方开发者文档为基础系统讲解 Archery——一个用 Python 编写、专为 Arrow 开发者设计的命令行工具。Archery 将 Arrow 开发中最繁琐的日常任务C 构建初始化、多语言 lint、基准测试、Docker 构建编排、CI 打包调度统一封装为独立子命令。读完本文你将掌握 Archery 的安装方式、全局与子命令用法并能熟练使用archery build、archery lint、archery benchmark、archery docker与archery crossbow完成本地开发与 CI 协作。Archery 是什么在 Daily Development using Archery 文档中Archery 被定位为为简化日常开发任务而开发的 Python 工具。它的本质是一个基于 Click 框架的 CLI 应用入口定义在 dev/archery/archery/cli.py安装后注册为archery控制台命令见 dev/archery/setup.py 中的entry_points。Archery 的模块化设计非常清晰功能按子包拆分且与安装方式一一对应功能领域源码模块典型用途benchmarkarchery/benchmark/运行 C/Java 基准测试并对比结果buildarchery/cli.pyarchery/lang/cpp.py初始化 Arrow C 构建目录dockerarchery/docker/编排 docker-compose 构建integrationarchery/integration/执行协议与 Flight 集成测试linkingarchery/linking.py检查动态库链接依赖lintarchery/utils/lint.py对源码树执行多语言 lintcrossbowarchery/crossbow/在 CI 服务上调度打包或 nightly 构建releasearchery/release/版本发布相关命令botarchery/bot.py处理 GitHub 评论触发的工作流安装 Archery官方文档要求Python 3.8 或更高版本。推荐使用-eeditable可编辑模式安装这样每次拉取 Arrow 仓库更新后安装的 Archery 也会自动同步无需重新安装。在克隆仓库后从仓库顶层目录执行$ pip install -e dev/archery[all]从 dev/archery/setup.py 可以看出[all]是以下所有 extras 依赖的并集extras[all] list(set(functools.reduce(operator.add, extras.values())))[benchmark]pandas用于基准测试结果对比与格式化[crossbow]github3.py、jinja2、pygit2、requests、ruamel.yaml、setuptools_scm[crossbow-upload]github3.py、jinja2、ruamel.yaml、setuptools_scm[docker]ruamel.yaml、python-dotenv用于解析.env文件[integration]cffi[integration-java]jpype1[lint]numpydoc、autopep8、flake8、cython-lint、cmake_format、sphinx-lint[numpydoc]numpydoc[release]pygithub、jinja2、jira、semver、gitpython[bot]crossbow 依赖 pygithub、jira如果你只想使用部分功能也可以按需安装。例如只做 lintpip install -e dev/archery[lint]只做 docker 编排pip install -e dev/archery[docker]。这一设计在 dev/archery/README.md 中有明确说明。此外Archery 的许多操作依赖 Docker 与 docker-compose。官方文档建议同时安装它们——Docker 主要面向 Linux 下的 CI 任务将 CI 配置与公共 CI 服务解耦从而保证本地可复现性详见 Running Docker Builds。全局用法与顶层命令Archery 的顶层命令通过archery --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对照 dev/archery/archery/cli.py 的实现三个全局选项的语义分别是--debug把日志级别提升到 DEBUG也可通过环境变量ARCHERY_DEBUG开启在archery docker场景下还会输出docker version等调试信息--pdb当命令抛出未捕获异常时自动进入pdb调试器通过替换sys.excepthook实现-q/--quiet静默模式抑制被执行的子命令的输出例如archery --quiet benchmark diff result.json可无干扰地把对比结果重定向到文件。每个子命令都有独立的帮助输出例如$ 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.用archery build初始化 C 构建archery build的用途是初始化一个 Arrow C 构建目录它创建一个目录用 Arrow 的 C CMake 配置进行初始化还可以按需调用生成器generator执行构建目标。从源码看它的核心逻辑是构造CppCMakeDefinition并调用cmake_def.build(build_dir, forceforce)随后对每个--targets执行build.run(target)。常用选项取自 dev/archery/archery/cli.py 的build命令定义工具链--cc、--cxx、--cxx-flags、--cpp-package-prefix构建类型--build-type可选debug/relwithdebinfo/release告警级别--warn-leveleverything/checkin/production控制-W(no-)error链接器与 SIMD--use-gold-linker对应ARROW_USE_LD_GOLD、--simd-levelNONE/SSE4_2/AVX2/AVX512测试与基准--with-tests、--with-benchmarks、--with-examples、--with-integration静态检查--use-asan、--use-tsan、--use-ubsan、--with-fuzzing组件开关--with-compute、--with-csv、--with-cuda、--with-dataset、--with-filesystem、--with-flight、--with-gandiva、--with-gcs、--with-hdfs、--with-ipc、--with-json、--with-mimalloc、--with-parquet、--with-python、--with-r、--with-s3等压缩库--with-brotli、--with-bz2、--with-lz4、--with-snappy、--with-zlib、--with-zstd其他--cmake-extras可叠加的额外 CMake 参数、--install-prefix默认取$CONDA_PREFIX、-f/--force删除已有构建目录、--targets可叠加的生成器目标命令示例# 用 clang-8 并开启 avx2 初始化构建目录 clang8-build $ archery build --ccclang-8 --cxxclang-8 --cxx-flags-mavx2 clang8-build # 构建并运行测试 $ archery build --targetsall --targetstest build需要注意的是archery build会继承调用者的环境变量它不会触碰已存在的构建目录除非显式传入--force。用archery lint做多语言静态检查archery lint的目标是检查 Arrow 源码树中的错误。所有检查默认关闭需要至少启用一个否则会抛出 UsageError。检查项在 dev/archery/archery/cli.py 中以lint_checks列表定义并以--check/--no-check开关形式暴露检查项作用clang-format格式化 C 文件clang-tidy对 C 文件做静态分析cpplint用 cpplint 检查 C 文件iwyu用 Include-What-You-Use 检查变更的 C 文件python用 autopep8 与 flake8 格式化/检查 Python 文件numpydoc用 numpydoc 检查 Python docstringcmake-format用 cmake-format.py 格式化 CMake 文件rat用 Apache RAT 检查所有源文件的许可文本r检查 R 文件调用r/lint.shdocker用 hadolint 检查 Dockerfiledocs用 sphinx-lint 检查文档典型用法# 启用所有检查 $ archery lint --all # 只做 Python 检查并自动修复 $ archery lint --python --fix # 只检查 C 格式 $ archery lint --clang-format从 dev/archery/archery/utils/lint.py 的实现可以看到几个值得注意的细节C 相关检查clang-format/cpplint/clang-tidy/iwyu依赖一个 CMake 构建目录生成的compile_commands.jsonRAT 检查通过git archive生成压缩包后交给 apache-rat 验证因此未提交的变更不会被检查到。lint 失败时命令会以非零退出码结束sys.exit(1)适合接入 CI。archery benchmark基准测试三件套archery benchmark是一个命令组包含三个子命令list、run、diff。它们统一支持--language目前支持cpp与java、--suite-filter/--benchmark-filter正则过滤等选项。列出基准测试套件$ archery benchmark list默认作用于当前工作区WORKSPACE也可传入 git revision如HEAD~1或已有的 CMake 构建目录。运行基准测试archery benchmark run为单次构建执行基准测试并捕获可选发布结果# 在当前 git 工作区运行 $ archery benchmark run # 在已有构建目录上运行 $ archery benchmark run /build/cpp # 在上一提交上运行 $ archery benchmark run HEAD~1 # 输出为 JSON 文件 $ archery benchmark run --outputrun.json关于重复次数C 默认 1 次、Java 默认 5 次可用--repetitions调整--repetition-min-time仅对 C 有效用于指定每次重复的最短时长秒。当引用 commit 时Archery 会基于--src指定的 Arrow 源码执行本地 clone 并创建相应分支--preserve可保留这个临时目录以便排查。特殊 tokenWORKSPACE表示当前 git 工作区不会执行 clone。对比基准测试结果archery benchmark diff被描述为类似 git-diff但作用于基准测试结果# 对比当前工作区contender与主开发分支baseline $ archery benchmark diff # 对比主开发分支与最新发布 tag $ export LAST$(git tag -l apache-arrow-[0-9]* | sort -rV | head -1) $ archery benchmark diff default-branch $LAST # 对比两种编译器构建 $ archery build --with-benchmarkstrue --cxx-flags-ftree-vectorize \ --ccgcc-7 --cxxg-7 gcc7-build $ archery build --with-benchmarkstrue --cxx-flags-flax-vector-conversions \ --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)Kernelcontender 与 baseline 均可为 git revision 或构建目录从而支持跨 commit、跨编译器、跨编译选项的比较。--threshold控制回归失败阈值默认值在 dev/archery/archery/benchmark/compare.py 的DEFAULT_THRESHOLD中定义单位为百分比。结果默认按Non-regressions与Regressions分组并以表格输出--no-counters可隐藏 counters 字段。值得注意的工程细节benchmark run的 runner 只有在被要求 JSON 序列化时才会真正干活因此即使未指定--output也会生成 JSONbenchmark diff也支持直接拿run.json缓存结果对比而无需重跑$ archery benchmark run --outputrun.json HEAD~1 $ archery --quiet benchmark diff WORKSPACE run.json result.jsonarchery dockerdocker-compose 构建编排子命令总览archery docker命令组dev/archery/archery/docker/cli.py实际提供了 7 个子命令check-config校验 docker-compose 配置、pull、build、run、push、images、info。官方文档重点演示了images与run# 列出可用的 docker-compose 镜像 $ archery docker images # 执行 conda-python 构建 $ 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这里体现了 Archery 的核心能力它读取仓库根目录 docker-compose.yml 中的x-hierarchy元数据自动识别镜像间的父子依赖如conda-python依赖conda-cpp从而把拉取、构建、运行整条链路的 docker-compose 命令按正确顺序执行避免手工逐个调用。常用运行选项只打印命令而不执行dry-run$ archery docker run --dry-run conda-python禁用镜像拉取$ archery docker run --no-cache conda-python等价于docker-compose build --no-cache conda-cpp docker-compose build --no-cache conda-python docker-compose run --rm conda-python。只对 leaf叶子镜像禁用缓存——用于强制构建某个依赖的开发版本。例如下面命令会构建conda-cpp conda-python conda-python-pandas镜像链其中 leaf 是conda-python-pandas$ PANDASupstream_devel archery docker run --no-leaf-cache conda-python-pandas等价于$ export PANDASupstream_devel $ 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 build --no-cache conda-python-pandas $ docker-compose run --rm conda-python-pandas注意这里不会拉取conda-python-pandas镜像且构建它时禁用缓存。PANDAS是一个构建参数默认值定义在仓库顶层的 .env 文件中。完全跳过构建阶段由于 docker-compose 的层缓存机制在不同版本、cache_from配置和构建后端docker-py、docker-cli、buildkit下可能产生不同的层哈希导致重复执行相同构建命令也出现缓存 miss 和全量重建。如果镜像已经构建成功而缓存失效可以这样跳过 pull 和 build 阶段# 第一次运行确保镜像已构建 $ archery docker run conda-python # 若第二次仍尝试重建且相关文件未变说明出现了上述缓存问题 $ archery docker run conda-python # 镜像已正确构建手动关闭 pull 与 build 以节省时间 $ archery docker run --no-pull --no-build conda-python向容器传递环境变量容器内的大多数构建脚本可通过环境变量配置用--env/-e传递与docker run/docker-compose run的接口一致$ archery docker run --env CMAKE_BUILD_TYPErelease ubuntu-cppC 构建可用的环境变量见 ci/scripts/cpp_build.sh 脚本。以自定义命令运行镜像第二个参数可传入自定义 docker 命令。下面的例子会在容器中启动交互式bash会话便于交互式调试构建$ archery docker run ubuntu-cpp bash其他参数-u/--user指定运行容器使用的用户名或 UID-v/--volume挂载卷如-v $PWD/build:/build ubuntu-cpp--build-only只拉取/构建镜像而不运行--resource-limit可套用 docker-compose.yml 中x-limit-presets预定义的 CPU/内存限制预设以模拟 GitHub Actions 等 CI 环境该选项强制要求--using-docker-cli。镜像拓扑与构建参数从 dev/archery/archery/docker/core.py 可以看到Archery 从docker-compose.yml中读取三类扩展元数据x-hierarchy服务名到祖先服务列表的映射驱动 pull/build/push 的自底向上执行顺序x-limit-presetsCPU/memory 限制预设供--resource-limit使用x-with-gpus需要 GPU 的服务名列表运行时会追加--gpus all要求 docker 19.03。配置加载时Archery 会用python-dotenv读取仓库顶层 .env 中的默认参数值再与调用者环境变量合并只有docker-compose.yml中引用到的键才会被接受并额外把 Docker 的架构记号翻译为通用命名ARCHamd64→ARCH_ALIASx86_64、ARCH_SHORTamd64arm64v8→ARCH_ALIASaarch64、ARCH_SHORTarm64。之后还会调用docker compose config做一次原生校验任何错误都会连同层次结构不一致service 未在x-hierarchy中登记等一起报出。Docker Volume 缓存大多数 compose 容器会在宿主机挂载特定目录以复用ccache和maven工件这些 docker 卷位于.docker目录。如需清理缓存直接删除其中一个或多个目录或整个.docker目录即可。后端切换与开发模式archery docker还支持三种构建后端切换通过选项或环境变量--using-legacy-docker-composeARCHERY_USE_LEGACY_DOCKER_COMPOSE使用传统docker-compose可执行文件而非内置的docker compose子命令适用于 Docker 客户端过旧的情形--using-docker-cliARCHERY_USE_DOCKER_CLI直接用 docker CLI 构建而非docker compose有助于复用缓存层--using-docker-buildxARCHERY_USE_DOCKER_BUILDX用 buildx 构建构建缓存可跨主机复用。在开发模式--debug下Archery 会输出--progressplain让 docker 日志更易读。镜像层次设计从 Running Docker Builds 可知docker-compose 配置面向可复用开发容器做了层次化设计多个语言绑定依赖 C 实现因此 Glib、Ruby、R、Python 绑定可以复用同一个基础 C 镜像而不是在每个 Dockerfile 里重复定义 C 环境。这减少了重复、简化了维护代价是 compose 配置更复杂——这正是由 Archery 的x-hierarchy机制来打理的。构建脚本约定ci/scripts 目录下的脚本应当保持可参数化但尽量精简每个脚本只清晰封装单一职责例如cpp_build.sh构建 C 实现不跑测试cpp_test.sh执行 C 测试python_build.sh构建 Python 绑定不跑测试python_test.sh执行 Python 测试integration_dask.sh/integration_pandas.sh执行 dask / pandas 集成测试install_minio.sh/install_conda.sh/install_gcs_testbench.sh为多平台安装 minio、miniconda、GCS testbench。参数化如 C 的 CMake 选项通过带默认值环境变量完成保持构建配置的声明式风格。典型例子是cpp_build.sh将环境变量转发为 CMake 选项同一个脚本可以在不同配置下被调用而无需修改。archery crossbowCI 打包与 nightly 构建调度archery crossbowdev/archery/archery/crossbow/cli.py用于在 CI 服务上调度打包任务或 nightly 构建。它把任务定义默认来自 dev/tasks/tasks.yml与目标 commit 渲染成 CI 配置提交到独立的 queue 仓库再由 CI 服务执行。主要选项包括-t/--github-token环境变量CROSSBOW_GITHUB_TOKENGitHub OAuth token-a/--arrow-path、-q/--queue-pathArrow 仓库与 queue 仓库路径submit子命令-g/--group提交任务组、-p/--param额外任务参数、--job-prefix分支名前缀如nightly、--arrow-version/-v、--arrow-remote/-r、--arrow-branch/-b、--arrow-sha/-t、--dry-run/--commit只渲染 CI 配置而不提交、--no-push/--push。流程上submit先校验tasks.yml根据仓库生成目标 revision可通过-r/-b/-t覆盖简化发布流程再queue.fetch()同步 queue 仓库并queue.put()提交任务。还提供了check-config子命令用于只加载、校验并展示任务配置。archery integration与其余命令集成测试archery integration执行协议IPC、Flight、C Data Interface集成测试支持的语言有 cpp、csharp、java、js、go、nanoarrow、rust。必须至少启用一种语言与一种格式例如$ archery integration --with-cpp --run-ipc --run-flight --run-c-data--with-all可一次性包含所有已知语言--random-seed默认 12345用于保证生成测试数据的确定性-x/--stop-on-error遇到首个错误即停止-k/--match按子串过滤测试名。linking、numpydoc、trigger-bot、releasearchery linking check-dependencies快速检查动态库依赖支持-a/--allow与-d/--disallow指定允许/禁止的库名见 dev/archery/archery/linking.py。archery numpydoc对 pyarrow 模块做 NumpyDoc docstring 校验例如archery numpydoc pyarrow.dataset、archery numpydoc pyarrow.csv pyarrow.json pyarrow.parquet默认禁用规则为GL01, SA01, EX01, ES01可用-a/--allow-rule与-d/--disallow-rule调整。archery trigger-bot以 GitHub webhook 事件为输入驱动评论机器人CommentBot与 PR 工作流机器人PullRequestWorkflowBot用于响应 PR 中的github-actions命令。archery release发布相关命令组由add_optional_command按需加载见 dev/archery/archery/release/cli.py。小结Archery 是 Apache Arrow 开发者日常工作的瑞士军刀build负责把 C 构建目录初始化得又快又规范lint一站式覆盖 C/Python/CMake/R/Docker/文档检查benchmark提供 list/run/diff 三件套支撑性能回归分析docker借助x-hierarchy与.env参数把复杂的层次化镜像构建编排得井井有条crossbow则把 nightly 打包任务可靠地调度到 CI 上。它的所有能力都以 dev/archery 下的模块化源码实现并配有 dev/archery/archery/docker/tests/test_docker.py、dev/archery/archery/crossbow/tests 等测试用例保障行为稳定。无论你是想快速搭建本地 C 构建、在提交前跑一遍全量 lint还是希望在本地复现 CI 的 Docker 构建Archery 都是值得先掌握的第一件工具。【免费下载链接】arrowApache Arrow is a multi-language toolbox for accelerated data interchange and in-memory processing项目地址: https://gitcode.com/gh_mirrors/arrow12/arrow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考