在您自己的项目中使用 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.16)

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_FOUND} 为真，如果找到了 Arrow C++ 库

  • ${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));
本页内容
在 GitHub 上编辑