在您自己的项目中使用 Arrow C++#

本节假设您的系统上已经安装了 Arrow C++ 库，无论是通过使用包管理器安装，还是自己构建。

将 Arrow C++ 库集成到您自己的 C++ 项目中的推荐方法是使用 CMake 的 find_package 函数来定位和集成依赖项。如果您不使用 CMake 作为构建系统，可以使用 pkg-config 来查找已安装的 Arrow C++ 库。

CMake#

基本用法#

这个最简单的 CMakeLists.txt 文件将 my_example.cc 源文件编译成一个可执行文件，并与 Arrow C++ 共享库链接

cmake_minimum_required(VERSION 3.25)

project(MyExample)

find_package(Arrow REQUIRED)

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

可用变量和目标#

指令 find_package(Arrow REQUIRED) 要求 CMake 在您的系统上找到一个 Arrow C++ 安装。当它返回时，它将设置一些 CMake 变量

  • 如果找到了 Arrow C++ 库，${Arrow_FOUND} 为 true

  • ${ARROW_VERSION} 包含 Arrow 版本字符串

  • ${ARROW_FULL_SO_VERSION} 包含 Arrow DLL 版本字符串

此外，它还会创建一些您可以链接的目标（请注意，这些是纯字符串，而不是变量）

  • Arrow::arrow_shared 链接到 Arrow 共享库

  • Arrow::arrow_static 链接到 Arrow 静态库

为了向后兼容，arrow_shared 和 arrow_static 目标也可用，但我们建议分别使用 Arrow::arrow_shared 和 Arrow::arrow_static。

在大多数情况下，建议使用 Arrow 共享库。

如果 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}}

注意

我们的 find_package 实现目前不支持使用 COMPONENTS。

其他可用包#

还有其他可用的包，它们也可以与 find_package 指令一起使用。这是可用包的列表

  • ArrowCUDA

  • ArrowAcero

  • ArrowCompute

  • ArrowDataset

  • ArrowFlight

  • ArrowFlightSql

  • ArrowFlightTesting

  • ArrowSubstrait

  • ArrowTesting

  • Gandiva

  • Parquet

与 find_package 和目标名称的使用遵循一致的命名模式

  • find_package 用法： find_package(PackageName REQUIRED)

  • 共享目标： PackageName::package_name_shared

  • 静态目标： PackageName::package_name_static

例如，要使用 ArrowCompute 包

  • find_package 用法： find_package(ArrowCompute REQUIRED)

  • 共享目标： ArrowCompute::arrow_compute_shared

  • 静态目标： ArrowCompute::arrow_compute_static

注意

CMake 对大小写敏感。上面列出的名称和变量必须完全按此拼写！

另请参阅

一个基于 Docker 的最小构建示例。

pkg-config#

基本用法#

您可以通过以下命令行获取合适的构建标志

pkg-config --cflags --libs arrow

如果您想链接 Arrow C++ 静态库，您需要添加 --static 选项

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

这个最简单的 Makefile 文件将 my_example.cc 源文件编译成一个可执行文件，并与 Arrow C++ 共享库链接

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

许多构建系统都支持 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

关于链接的注意事项#

一些 Arrow 组件具有您可能希望在自己的项目中使用 的依赖项。必须注意确保您的项目以相同的方式（静态或动态）链接这些依赖项的相同版本，否则可能导致 ODR 违规，您的程序可能会崩溃或悄无声息地损坏数据。

特别是，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 版本，您可以在其中控制每个依赖项的来源以及它是静态链接还是动态链接。有关说明，请参阅构建 Arrow C++。或者，从 Conda 或 vcpkg 等包管理器使用 Arrow，它们将管理 Arrow 及其依赖项的一致版本。

运行时依赖项#

虽然 Arrow 在 Linux 和 macOS 上使用操作系统提供的时区数据库，但它在 Windows 上需要用户提供的数据库。您必须下载并提取 IANA 时区数据库的文本版本，并添加 Windows 时区映射 XML。要下载，您可以使用以下批处理脚本

默认情况下，时区数据库将在 %USERPROFILE%\Downloads\tzdata 检测到，但您可以在 arrow::ArrowGlobalOptions 中设置自定义运行时路径

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