在您自己的项目中使用 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 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。例如

GNU Autotools

CMake（但您应该使用 find_package(Arrow) 代替。）

Meson

可用软件包#

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));