在您專案中使用 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。例如

可用的套件#

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