在您自己的项目中使用 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 指令一起使用。 这是可用软件包的列表以及创建的相应目标

find_package 用法

共享目标

静态目标

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

注意

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 组件具有您可能希望在您自己的项目中使用的依赖项。 必须小心确保您的项目以与 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。 要下载，您可以使用以下批处理脚本

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

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

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