Apache Arrow C++ 构建系统集成指南:用 CMake 与 pkg-config 将 Arrow 库接入你自己的项目

原创2026-09-22 20:12:171,708 阅读
文章标签:数据工程数据分析大数据

Apache Arrow C++ 构建系统集成指南:用 CMake 与 pkg-config 将 Arrow 库接入你自己的项目

Apache Arrow 是一个面向加速数据交换与内存中处理的多语言工具箱,其 C++ 实现提供了高效的内存数据格式与列式处理能力。本文基于 Apache Arrow 官方 C++ 文档 build_system.rst,系统讲解如何在你自己的 C++ 项目中集成已经安装好的 Arrow C++ 库:包括使用 CMake 的 find_package 定位依赖、使用 pkg-config 获取编译链接参数、正确处理静态/动态链接一致性问题,以及 Windows 平台时区数据库等运行时依赖。读完本文,你将能写出最小可运行的 CMakeLists.txt 与 Makefile,并理解 Arrow 提供的全部 CMake 包与 pkg-config 包及其对应的链接目标。

前置条件:本文假定你的系统上已经安装了 Arrow C++ 库,无论是通过包管理器安装(官方安装指南见 arrow.apache.org/install/),还是参照 cpp 构建文档 自行从源码构建。集成你自己的项目时,推荐使用 CMake 的 find_package 函数定位并集成依赖;若你使用的不是 CMake 构建系统,则可以改用 pkg-config 查找已安装的 Arrow C++ 库。

CMake 集成:最小可运行示例

在 CMake 项目中集成 Arrow 最为简单的方式,是使用 find_package(Arrow REQUIRED) 让 CMake 自动定位系统上安装的 Arrow 安装。下面这份极简 CMakeLists.txt 将 my_example.cc 编译为一个与 Arrow C++ 动态库链接的可执行文件:

cmake_minimum_required(VERSION 3.16)

project(MyExample)

find_package(Arrow REQUIRED)

add_executable(my_example my_example.cc)
target_link_libraries(my_example PRIVATE Arrow::arrow_shared)

这份配置的最低 CMake 版本要求为 3.16,与仓库中的最小构建示例 cpp/examples/minimal_build/CMakeLists.txt 保持一致。仓库中的示例还补充了两处值得借鉴的实践:当 CMAKE_CXX_STANDARD 未定义时默认设为 17(Arrow C++ 要求 C++17 编译器,CMAKE_CXX_STANDARD_REQUIRED ON),并在未指定 CMAKE_BUILD_TYPE 时默认使用 Release。它还通过 option(ARROW_LINK_SHARED "Link to the Arrow shared library" ON) 暴露了一个开关,控制最终链接 Arrow::arrow_shared 还是 Arrow::arrow_static,方便你在两种链接方式间切换。

find_package 返回的变量与目标

find_package(Arrow REQUIRED) 返回后,会为你的项目设置以下几个 CMake 变量:

变量 含义
${Arrow_FOUND} 若系统上找到了 Arrow C++ 库则为真(true)
${ARROW_VERSION} Arrow 版本字符串
${ARROW_FULL_SO_VERSION} Arrow DLL 版本字符串(shared library 完整版本)

同时它还会创建若干可供你链接的 target(注意这些是普通字符串,不是变量):

目标 作用
Arrow::arrow_shared 链接到 Arrow 动态库(shared libraries)
Arrow::arrow_static 链接到 Arrow 静态库(static libraries)

出于向后兼容目的,不带命名空间的 arrow_shared 与 arrow_static 目标也仍然可用,但我们推荐优先使用带命名空间的 Arrow::arrow_shared 与 Arrow::arrow_static。在大多数场景下,建议使用 Arrow 的动态库。

从源码看,这些变量与目标的生成逻辑定义在 cpp/src/arrow/ArrowConfig.cmake.in 中:配置模板通过 @ARROW_VERSION@、@ARROW_SO_VERSION@、@ARROW_FULL_SO_VERSION@ 占位符在构建时被真实版本号替换,并生成 ArrowOptions.cmake(记录构建时启用的 ARROW_* 选项)与 ArrowTargets.cmake(导出 import targets)。值得一提的是,模板底部通过 arrow_keep_backward_compatibility(Arrow arrow) 宏(见 ArrowConfig.cmake.in)为旧式 arrow_shared/arrow_static 目标建立 ALIAS,这正是文档所说"向后兼容目标仍可用"的机制来源。若你启用了静态构建(ARROW_BUILD_STATIC),配置还会自动 find_dependency 查找 Arrow 的系统级依赖,并为静态链接场景创建 Arrow::arrow_bundled_dependencies 导入目标来聚合被捆绑的第三方静态库。

自定义安装路径与 CMAKE_PREFIX_PATH

如果 Arrow 安装在了自定义路径而非常见的系统路径,你需要把 Arrow 的安装路径加入 CMAKE_PREFIX_PATH。CMAKE_PREFIX_PATH 既可以作为 CMake 变量传入,也可以通过环境变量定义。如果你的系统已经定义了 CMAKE_PREFIX_PATH 环境变量,可以用下面的命令将其展开并追加 Arrow 安装路径(此处 ARROW_ROOT 应包含你的 Arrow 安装路径):

export CMAKE_PREFIX_PATH=${ARROW_ROOT}${CMAKE_PREFIX_PATH:+:${CMAKE_PREFIX_PATH}}

如果使用 CMake 变量方式,可在配置项目时这样追加,以保留可能已存在的 CMAKE_PREFIX_PATH 环境变量:

cmake ... -DCMAKE_PREFIX_PATH=${ARROW_ROOT}${CMAKE_PREFIX_PATH:+:${CMAKE_PREFIX_PATH}}

注意:当前 Arrow 的 find_package 实现不支持 COMPONENTS 用法。

其他可用包(find_package 完整清单)

除了核心的 Arrow 包之外,Arrow C++ 还提供多个模块包,同样通过 find_package 指令使用。下表列出全部可用包及其对应的共享/静态目标,使用时 CMake 是区分大小写的,包名与目标名必须严格按表中写法拼写:

find_package 用法 共享目标(shared target) 静态目标(static target)
find_package(ArrowCUDA REQUIRED) ArrowCUDA::arrow_cuda_shared ArrowCUDA::arrow_cuda_static
find_package(ArrowDataset REQUIRED) ArrowDataset::arrow_dataset_shared ArrowDataset::arrow_dataset_static
find_package(ArrowFlight REQUIRED) ArrowFlight::arrow_flight_shared ArrowFlight::arrow_flight_static
find_package(ArrowFlightSql REQUIRED) ArrowFlightSql::arrow_flight_sql_shared ArrowFlightSql::arrow_flight_sql_static
find_package(ArrowFlightTesting REQUIRED) ArrowFlightTesting::arrow_flight_testing_shared ArrowFlightTesting::arrow_flight_testing_static
find_package(ArrowSubstrait REQUIRED) ArrowSubstrait::arrow_substrait_shared ArrowSubstrait::arrow_substrait_static
find_package(ArrowTesting REQUIRED) ArrowTesting::arrow_testing_shared ArrowTesting::arrow_testing_static
find_package(Gandiva REQUIRED) Gandiva::gandiva_shared Gandiva::gandiva_static
find_package(Parquet REQUIRED) Parquet::parquet_shared Parquet::parquet_static

这些模块与仓库源码目录一一对应:ArrowCUDA 对应 cpp/src/arrow/gpu,ArrowDataset 对应 cpp/src/arrow/dataset,ArrowFlight 对应 cpp/src/arrow/flight,ArrowSubstrait 对应 cpp/src/arrow/engine,Gandiva 对应 cpp/src/gandiva,Parquet 对应 cpp/src/parquet。

另外,官方还提供了一个 Docker 化的最小构建示例供参考:examples/cmake_minimal_build。该示例位于 cpp/examples/minimal_build/README.md,包含两阶段内容:先用 build_arrow.sh 最小化构建 Arrow C++,再让一个第三方示例项目通过 CMakeLists.txt 编译链接 Arrow 库;运行 docker-compose run --rm minimal 即可复现。示例程序会读取 test.csv、打印解析内容并把结果以 Arrow IPC 格式写入 test.arrow,其完整代码见 cpp/examples/minimal_build/example.cc。该目录还提供了静态链接(docker-compose run --rm static)与针对系统依赖静态链接(static-system-dependency)的示例配置。

pkg-config 集成:获取编译与链接参数

如果不使用 CMake 构建系统,可以使用 pkg-config 获取合适的编译标志。基本用法如下,它会输出编译所需的头文件路径(--cflags)与链接所需的库路径和库名(--libs):

pkg-config --cflags --libs arrow

如果需要链接 Arrow C++ 静态库,需加上 --static 选项:

pkg-config --cflags --libs --static arrow

下面这份最小 Makefile 使用上述命令将 my_example.cc 编译为可执行文件:

my_example: my_example.cc
    $(CXX) -o $@ $(CXXFLAGS) $< $$(pkg-config --cflags --libs arrow)

许多构建系统都支持 pkg-config,例如 GNU Autotools、CMake(通过 FindPkgConfig 模块;但在 CMake 项目中仍应优先使用 find_package(Arrow))、以及 Meson(通过 dependency 函数)。从仓库中的模板 cpp/src/arrow/arrow.pc.in 可以看到 .pc 文件的具体生成方式:它记录了安装前缀、include 与 lib 目录,并以 Requires/Requires.private、Libs/Libs.private、Cflags 等字段区分公开与私有依赖信息,--static 选项正是把 *.private 字段一并纳入链接。

可用的 pkg-config 包清单

Arrow C++ 为每个模块都提供了一个 pkg-config 包,全部可用包如下:

  • arrow-csv
  • arrow-cuda
  • arrow-dataset
  • arrow-filesystem
  • arrow-flight-testing
  • arrow-flight
  • arrow-json
  • arrow-orc
  • arrow-python-flight
  • arrow-python
  • arrow-tensorflow
  • arrow-testing
  • arrow
  • gandiva
  • parquet

这些包与源码中的 .pc.in 模板一一对应,例如 cpp/src/arrow/csv/arrow-csv.pc.in、cpp/src/arrow/filesystem/arrow-filesystem.pc.in、cpp/src/arrow/json/arrow-json.pc.in、cpp/src/arrow/adapters/orc/arrow-orc.pc.in、cpp/src/arrow/flight/arrow-flight.pc.in、cpp/src/arrow/flight/sql/arrow-flight-sql.pc.in、cpp/src/arrow/gpu/arrow-cuda.pc.in、cpp/src/arrow/arrow-testing.pc.in、cpp/src/gandiva/gandiva.pc.in、cpp/src/parquet/parquet.pc.in 等。其中 arrow-testing 的模板还通过 Requires: arrow 显式声明了对核心 arrow 包的依赖(见 cpp/src/arrow/arrow-testing.pc.in)。

链接方式一致性:避免 ODR 违规

某些 Arrow 组件自身带有依赖项,而你可能也想在自己的项目中使用这些依赖。务必保证你的项目以与 Arrow 相同的方式(静态或动态)链接相同版本的这些依赖,否则可能引发 ODR(One Definition Rule)违规,导致程序崩溃或在静默中损坏数据。

尤其容易出问题的是 Arrow Flight 及其依赖的 Protocol Buffers(Protobuf)与 gRPC。使用 Arrow Flight 时请注意以下准则:

  • 如果静态链接 Arrow Flight,则 Protobuf 和 gRPC 也必须静态链接;动态链接同理,必须保持一致。
  • 某些平台(例如撰写本文时的 Ubuntu 20.04)自带的 Protobuf 和/或 gRPC 版本可能不足以满足 Arrow Flight 的要求。此时 Arrow Flight 会捆绑这些依赖,因此务必小心:不要把 Arrow Flight 库与平台自带的 Protobuf/gRPC 库混用(否则你的应用程序中会同时链接两份 Protobuf 和/或 gRPC)。

最简单的规避方案,是依赖一个从源码构建的 Arrow 版本,这样你可以完全控制每个依赖的来源及其静态/动态链接方式(构建说明见 cpp 构建文档);或者使用 Conda、vcpkg 这类包管理器提供的 Arrow,它们会统一管理 Arrow 与其依赖的版本一致性。仓库中的最小构建示例也提供了静态链接的参考实现:Linux 上运行 docker-compose run --rm static,macOS 上先导出 ARROW_DIR、EXAMPLE_DIR、ARROW_BUILD_DIR、EXAMPLE_BUILD_DIR 环境变量再执行 ./run_static.sh,Windows 上在 Visual Studio 命令行工具环境中执行 run_static.bat;若想针对系统库静态链接,可设置 ARROW_DEPENDENCY_SOURCE=SYSTEM 或运行 docker-compose run --rm static-system-dependency(详见 cpp/examples/minimal_build/README.md)。

运行时依赖:Windows 时区数据库

Linux 与 macOS 上 Arrow 使用操作系统自带的时区数据库,但 Windows 上则需要用户提供时区数据库。你必须下载并解压 IANA 时区数据库的文本版本,并额外添加 Windows 时区映射 XML。下载操作可以直接使用官方 CI 脚本中的批处理片段(见 ci/appveyor-cpp-setup.bat):

@rem (Doc section: Download timezone database)
curl https://data.iana.org/time-zones/releases/tzdata2021e.tar.gz --output tzdata.tar.gz
mkdir tzdata
tar --extract --file tzdata.tar.gz --directory tzdata
move tzdata %USERPROFILE%\Downloads\tzdata
@rem Also need Windows timezone mapping
curl https://raw.githubusercontent.com/unicode-org/cldr/master/common/supplemental/windowsZones.xml ^
  --output %USERPROFILE%\Downloads\tzdata\windowsZones.xml
@rem (Doc section: Download timezone database)

默认情况下,Arrow 会在 %USERPROFILE%\Downloads\tzdata 路径检测时区数据库,但你可以在运行时通过 arrow::ArrowGlobalOptions 设置自定义路径:

arrow::GlobalOptions options;
options.timezone_db_path = "path/to/tzdata";
ARROW_RETURN_NOT_OK(arrow::Initialize(options));

从源码可以印证这一机制的底层实现:arrow::GlobalOptions 定义在 cpp/src/arrow/config.h,其 timezone_db_path 字段注释明确指出该路径仅在 Windows 上可配置(Windows 没有可用的操作系统时区数据库)。arrow::Initialize 的实现位于 cpp/src/arrow/config.cc:当传入 timezone_db_path 时,若 Arrow 编译时未启用 OS 时区数据库(USE_OS_TZDB 未定义),它会调用 arrow_vendored::date::set_install 与 arrow_vendored::date::reload_tzdb 重新加载时区数据库并缓存该路径;反之,若编译时启用了 OS 时区数据库,则在运行时提供下载数据库会返回 Status::Invalid 错误。此外,config.h 中的 GetBuildInfo() 返回的是运行时实际加载的库版本信息(含 using_os_timezone_db 标志),而非编译期冻结的宏值,可用来在运行时校验所链接 Arrow 的时区数据库行为。

总结

将 Arrow C++ 集成进自己的项目有两条成熟路径:CMake 场景下用 find_package(Arrow REQUIRED) 配合 Arrow::arrow_shared/Arrow::arrow_static 目标(以及各模块包的对应目标),并在自定义安装路径时正确配置 CMAKE_PREFIX_PATH;非 CMake 场景下用 pkg-config --cflags --libs arrow 获取编译链接参数(静态链接加 --static)。无论走哪条路径,都要保证依赖以与 Arrow 一致的静态/动态方式链接相同版本,避免 ODR 违规;在 Windows 上运行还需准备 IANA 时区数据库并通过 arrow::Initialize 在运行时指定路径。掌握这些要点后,你就能在自己的 C++ 项目中稳定、正确地接入 Arrow 的列式内存格式与高速数据处理能力。

登录后查看全文
arrow