Apache Arrow 从源码构建指南CMake、Presets 与 PyArrow/R 开发工作流【免费下载链接】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、C#、Go、Java、JavaScript、Julia 和 Rust 各自拥有独立的 Arrow 实现而 CGlib、MATLAB、Python、R 和 Ruby 则构建在 C 库之上。本文以 docs/source/developers/guide/step_by_step/building.rst 为骨架系统讲解为什么要从源码构建 Arrow C、CMake 的工作机制与 Presets 用法、可选构建标志以及如何基于本地 C 库迭代开发 PyArrow 与 R 包。读完本文你将掌握完整的从源码构建与增量重编译流程能够在自己修改的 C/Cython/R 代码上运行测试。一、Arrow 多语言库的两种构建形态Arrow 项目是一个多语言工具箱不同语言实现与 C 库的关系分为两类独立实现C、C#、Go、Java、JavaScript、Julia、Rust 各自包含完整的 Arrow 核心实现可以独立构建基于 C 的上层绑定CGlib、MATLAB、Python、R、Ruby 的 Arrow 库是围绕 C 实现编写的包装层与接口。这意味着如果你要开发 PyArrow 或 R 包除了修改对应语言层的源码往往还需要修改乃至重编译底层的 C 代码——这是理解整个构建流程的起点。相关语言的具体构建说明分散在各自的开发文档中例如 C 详见 docs/source/developers/cpp/building.rstPyArrow 详见 docs/source/developers/python/building.rst。二、为什么需要从源码构建 Arrow C对于构建在 C 实现之上的语言如 Python 和 R其包装层和接口直接调用底层的 C 函数。使用官方发布二进制包虽然简单快捷但无法修改 Arrow C 库本身。当你希望修改 PyArrow 或 R 包中依赖的 C 行为在本地调试、加日志、改算法后立即验证效果为 Arrow C 贡献代码并运行测试就必须从源码编译 Arrow C。详细的 C 构建步骤参见 docs/source/developers/cpp/building.rst。三、认识 CMake构建系统生成器3.1 CMake 是什么CMake 是一个跨平台的构建系统生成器cross-platform build system generator它本身并不直接编译代码而是把构建配置转交给另一个程序如make或ninja去执行实际的编译。在 Arrow 中CMake 负责解析各类-D选项组件开关、依赖来源、编译类型探测系统环境与第三方依赖生成构建规则再由 Ninja/Make 完成编译。从源码结构看Arrow C 的全部构建逻辑集中在 cpp/CMakeLists.txt 及 cpp/cmake_modules 目录下的众多 CMake 模块中。3.2 系统要求与安装依赖依据 docs/source/developers/cpp/building.rst从源码构建 Arrow C 需要支持C20的编译器Linux 上 gcc 12 及以上CMake 3.25 或更高Linux 与 macOS 上需要make或ninja构建工具内存建议最小构建至少 1GB带测试的最小 Debug 构建 4GB使用 Docker 的完整构建 8GB。以 Ubuntu/Debian 为例sudo apt-get install \ build-essential \ ninja-build \ cmakemacOS 可使用 Homebrewbrew bundle --filecpp/BrewfileWindows 开发者可参考 MSYS2 或 vcpkg 方式安装依赖详见 cpp 目录下的 Brewfile 与 vcpkg.json。3.3 构建类型Build TypeCMake 配置的核心参数之一是CMAKE_BUILD_TYPEArrow 支持三种构建类型优化调试信息适用场景Debug不应用优化包含日常开发、调试、跑测试RelWithDebInfo应用优化包含需要性能又要可调试Release应用优化移除发布、基准测试从 ci/scripts/cpp_build.sh 可以看出CI 默认CMAKE_BUILD_TYPE为debug对应ARROW_BUILD_TYPE:-debug并通过CMAKE_BUILD_PARALLEL_LEVEL控制并行度、用time cmake --build . --target install完成构建与安装。3.4 遇到构建错误怎么办构建出错时第一步是仔细通读错误信息并对照构建文档查找是否有同类错误建议其次可以尝试调整传给 CMake 的编译标志。Arrow 还提供了ARROW_EXTRA_ERROR_CONTEXT在 Debug preset 中默认开启等开关用于在错误信息中附加更多上下文便于定位问题。四、CMake Presets开箱即用的构建配方4.1 什么是 PresetsArrow 在 cpp/CMakePresets.json 中提供了一组构建与测试配方presets它们是开始构建的非常实用的起点。该文件基于 CMake Presets v3 规范要求 CMake 3.21通过inherits机制把「基础配置」与「功能组合」叠加成数十个可直接使用的命名 preset。4.2 Presets 的分层结构从 cpp/CMakePresets.json 的源码结构可以清晰看到三层设计基础层base定义生成器为Ninja、关闭静态库ARROW_BUILD_STATICOFF、开启编译命令导出CMAKE_EXPORT_COMPILE_COMMANDSON其下派生base-debug开启测试、集成测试、额外错误上下文、base-release、base-benchmarks功能层features-*按功能组合复用例如features-minimal关闭 mimalloc、RE2、utf8procfeatures-basic开启 Compute、CSV、Dataset、Filesystem、JSON、mimallocfeatures-main在 basic 基础上追加 Substrait、Acero、Parquet 以及 Brotli/BZ2/LZ4/RE2/Snappy/utf8proc/Zlib/Zstd 压缩与文本依赖features-python/features-python-maximal叠加 CUDA、文件系统Azure/GCS/HDFS/S3、Flight SQL、Gandiva、OpenTelemetry 与 ORCfeatures-emscripten面向 WebAssembly 的静态构建关闭线程、SIMD、Flight、S3。成品层ninja-*组合功能层与基础层供直接使用例如ninja-debug-minimal、ninja-debug-basic、ninja-debug、ninja-release、ninja-benchmarks等。此外还内置了 AddressSanitizerninja-debug-asan、ThreadSanitizerninja-debug-tsan、UndefinedBehaviorSanitizerninja-debug-ubsan、Valgrindninja-debug-valgrind-*以及fuzzing等专门用于质量保障的配方。4.3 Presets 的典型用法依据 docs/source/developers/cpp/building.rst 中的cmake_presets章节在cpp子目录内可以列出可用 presets$ cmake --list-presets Available configure presets: ninja-debug-minimal - Debug build without anything enabled ninja-debug-basic - Debug build with tests and reduced dependencies ninja-debug - Debug build with tests and more optional components [ etc. ]预览某个 preset 展开后的具体选项不实际配置$ cmake -N --preset ninja-debug-minimal Preset CMake variables: ARROW_BUILD_INTEGRATIONOFF ARROW_BUILD_STATICOFF ARROW_BUILD_TESTSOFF ARROW_EXTRA_ERROR_CONTEXTON ARROW_WITH_RE2OFF ARROW_WITH_UTF8PROCOFF CMAKE_BUILD_TYPEDebug基于 preset 创建构建目录并编译$ mkdir build $ cd build $ cmake .. --preset ninja-debug-minimal $ cmake --build . $ cmake --install .在 preset 基础上追加自定义选项例如$ cmake .. --preset ninja-debug-minimal -DCMAKE_INSTALL_PREFIX/usr/local注意Presets 只是帮助开发者快速上手的辅助配方官方明确提示它并不保证一成不变未来可能根据反馈调整。因此自动化构建、持续集成、发布脚本等应优先使用手动配置见下一节而不是依赖 presets。五、可选构建标志与环境变量5.1 标志的两大用途CMake 构建标志用于两件事加入附加组件和处理第三方依赖。Arrow C 的最小构建可以完全不使用任何标志按需打开开关即可引入相应组件。所有标志的默认值与语义都能在 CI 构建脚本 ci/scripts/cpp_build.sh 中找到第一手证据。5.2 常用组件开关基于 ci/scripts/cpp_build.sh 的默认值标志默认值含义ARROW_COMPUTEON计算内核库Kernel 与表达式求值ARROW_CSVONCSV 读写ARROW_FILESYSTEMON文件系统抽象ARROW_JSONONJSON 读写ARROW_DATASETOFFDataset API多文件、分区数据集ARROW_PARQUETOFFParquet 支持ARROW_ORCOFFORC 支持ARROW_CUDAOFFCUDA 支持ARROW_S3/ARROW_AZURE/ARROW_GCS/ARROW_HDFSOFF/OFF/OFF/ON各类文件系统后端ARROW_FLIGHT/ARROW_FLIGHT_SQLOFFFlight RPC 与 Flight SQLARROW_GANDIVAOFFGandiva 表达式编译器ARROW_ACEROOFF执行引擎查询执行ARROW_SUBSTRAITOFFSubstrait 计划支持ARROW_BUILD_TESTSOFF构建单元测试ARROW_BUILD_BENCHMARKSOFF构建基准测试ARROW_JEMALLOC/ARROW_MIMALLOCOFF/ON内存分配器ARROW_WITH_BROTLI/BZ2/LZ4/SNAPPY/ZSTD/ZLIBOFF压缩编解码器5.3 第三方依赖与依赖来源依赖处理通过ARROW_DEPENDENCY_SOURCE默认AUTO控制可取BUNDLED随源码编译第三方依赖、SYSTEM使用系统安装的库、VCPKG、CONDA等ARROW_DEPENDENCY_USE_SHARED决定链接共享还是静态依赖。此外像GTest_SOURCE、re2_SOURCE、AWSSDK_SOURCE等*_SOURCE变量可单独指定某个依赖的来源这在离线或受控环境中非常有用。CI 脚本还支持ARROW_OFFLINEON模式先通过cpp/thirdparty/download_dependencies.sh预下载依赖并生成enable_offline_build.sh再在断网环境下完成构建。5.4 Python 与 R 的差异不同上层语言传递构建参数的方式不同PythonPyArrow构建选项主要通过CMake 标志设置而路径如依赖库位置通过环境变量设置R 包几乎所有与构建相关的内容包括 CMake 标志都通过环境变量传递。这一差异是排查「标志不生效」类问题时的关键线索先确认你使用的是该语言约定的传参通道。六、构建 PyArrow分层构建与增量重编译6.1 为什么 C 与 PyArrow 要分开构建PyArrow 的 Python 部分构建在 C 库之上二者是独立的构建单元。为了能在本地同时修改 Python 代码和 C 代码需要分别构建先构建 Arrow C 库再在其上构建 PyArrow。6.2 重编译 CythonPyArrow 的 Cython 源码位于 python/pyarrow含大量.pyx、.pxd、.pxi文件。重编译规则如下只修改.py文件无需重编译直接运行即可修改了.pyx或.pxd文件需要重新编译 PyArrow重新执行该命令$ pip install --no-build-isolation --editable . -vv该命令在 docs/source/developers/python/building.rst 中有完整说明--no-build-isolation复用当前环境而非创建隔离构建环境--editable实现可编辑安装源码改动即时生效-vv输出详细日志便于排错。6.3 重编译 C同理只要修改了任何 C 文件就需要重新运行 C 的构建命令即第四节中的cmake --build .等步骤让修改后的 C 库重新编译并安装再视情况重装 PyArrow。七、构建 R 包libarrow 与 Makefile 工作流7.1 是否需要构建 libarrow在 R 包上开发时是否需要从源码构建 Arrow C 库R 文档中常称libarrow取决于你的操作系统与计划修改的范围——如果只改 R 层代码通常不需要重编 C 库如果改动涉及 C则必须重编。7.2 修改 C 后的三步流程若修改了 Arrow Clibarrow部分的代码需要依次执行重新安装 libarrow重跑 C 构建与安装运行make clean重新安装 R 包。make clean定义在 r/Makefile 中它会删除r/src/目录下缓存的.o、.so、.dll、Makevars、libarrow/以及tools/cpp/等对象代码与旧构建产物确保后续安装是干净的全新构建不会残留旧目标文件导致链接到过期代码。7.3 R Makefile 提供的常用任务从 r/Makefile 的源码可以看到该文件为命令行常用任务提供了多个目标除了clean之外还包括目标作用make test安装带测试的包并运行 testthat 测试套件make doc运行 roxygen2 生成文档man/*.Rdmake style/make style-all通过 pre-commit 检查 R 代码风格make deps安装 devtools 与开发依赖make sync-cpp将cpp/源码同步到tools/R 包内嵌 C 源码的机制make build先 clean、doc、sync-cpp再R CMD buildmake check/make release以--as-cran方式执行R CMD check其中sync-cpp揭示了 R 包的工作方式它把仓库根目录下的cpp/源码排除 apidoc、build、gandiva、odbc、jni、测试等同步进tools/cpp/并把.env改名为dotenv后替换 cpp/CMakeLists.txt 中的引用使 R 包构建时能就地编译内嵌的 C 源码。八、从源码构建 vs 使用二进制使用官方二进制包binaries是体验最近发布版本最快、最简单的方式。但代价是你将无法修改 Arrow C 库。对于仅使用 Arrow 的用户二进制是首选对于想贡献代码、调试底层实现、或需要在 C 层做定制改造的开发者从源码构建是必经之路。每种语言处理二进制的方式各不相同例如 Python 通过 pip 安装 wheel、R 通过 CRAN 包、各语言有各自的发布渠道如需了解具体语言请查阅该语言对应的开发文档章节。九、总结从源码构建 Apache Arrow 的整体路径可以概括为先理解 C 是上层语言Python/R 等的地基再用 CMakePresets 或手动标志编译 C最后在该库之上分别构建并增量重编译上层语言。掌握cmake --preset配方、ARROW_*组件开关、pip install --editable与make clean等关键操作后你就能在本地拥有一套可修改、可测试、可调试的完整 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），仅供参考