构建 Arrow C++#

系统设置#

Arrow 使用 CMake 作为构建配置系统。我们建议在源代码外部构建。如果您不熟悉此术语

  • 源代码内部构建：cmake 直接在 cpp 目录中调用。当您希望维护多个构建环境（例如，一个用于调试构建，另一个用于发布构建）时，这可能缺乏灵活性

  • 源代码外部构建：cmake 从另一个目录调用，创建一个与任何其他构建环境都不交互的独立构建环境。例如，您可以创建 cpp/build-debug 并从该目录调用 cmake $CMAKE_ARGS ..

构建需要

  • 支持 C++17 的编译器。在 Linux 上，gcc 7.1 及更高版本应该足够。对于 Windows，至少需要 Visual Studio VS2017。

  • CMake 3.16 或更高版本

  • 在 Linux 和 macOS 上，使用 make 或 ninja 构建工具

  • 至少 1GB 的 RAM 用于最小构建，4GB 用于带有测试的最小调试构建，以及 8GB 用于使用 docker 的完整构建。

在 Ubuntu/Debian 上，您可以使用以下命令安装所需软件包：

sudo apt-get install \
     build-essential \
     ninja-build \
     cmake

在 Alpine Linux 上

apk add autoconf \
        bash \
        cmake \
        g++ \
        gcc \
        ninja \
        make

在 Fedora Linux 上

sudo dnf install \
     cmake \
     gcc \
     gcc-c++ \
     ninja-build \
     make

在 Arch Linux 上

sudo pacman -S --needed \
     base-devel \
     ninja \
     cmake

在 macOS 上，您可以使用 Homebrew

git clone https://github.com/apache/arrow.git
cd arrow
brew update && brew bundle --file=cpp/Brewfile

使用 vcpkg

git clone https://github.com/apache/arrow.git
cd arrow
vcpkg install \
  --x-manifest-root cpp \
  --feature-flags=versions \
  --clean-after-build

在 MSYS2 上

pacman --sync --refresh --noconfirm \
  ccache \
  git \
  mingw-w64-${MSYSTEM_CARCH}-boost \
  mingw-w64-${MSYSTEM_CARCH}-brotli \
  mingw-w64-${MSYSTEM_CARCH}-cmake \
  mingw-w64-${MSYSTEM_CARCH}-gcc \
  mingw-w64-${MSYSTEM_CARCH}-gflags \
  mingw-w64-${MSYSTEM_CARCH}-glog \
  mingw-w64-${MSYSTEM_CARCH}-gtest \
  mingw-w64-${MSYSTEM_CARCH}-lz4 \
  mingw-w64-${MSYSTEM_CARCH}-protobuf \
  mingw-w64-${MSYSTEM_CARCH}-python3-numpy \
  mingw-w64-${MSYSTEM_CARCH}-rapidjson \
  mingw-w64-${MSYSTEM_CARCH}-snappy \
  mingw-w64-${MSYSTEM_CARCH}-thrift \
  mingw-w64-${MSYSTEM_CARCH}-zlib \
  mingw-w64-${MSYSTEM_CARCH}-zstd

构建#

以下所有说明都假设您已克隆 Arrow Git 存储库并导航到 cpp 子目录

$ git clone https://github.com/apache/arrow.git
$ cd arrow/cpp

CMake 预设#

使用 CMake 3.21.0 或更高版本，提供了一些用于各种构建配置的预设。您可以使用 cmake --list-presets 获取可用预设的列表

$ cmake --list-presets   # from inside the `cpp` subdirectory
Available configure presets:

  "ninja-debug-minimal"     - Debug build without anything enabled
  "ninja-debug-basic"       - Debug build with tests and reduced dependencies
  "ninja-debug"             - Debug build with tests and more optional components
   [ etc. ]

您可以使用 cmake -N --preset <preset name> 检查给定预设启用的特定选项

$ cmake --preset -N ninja-debug-minimal
Preset CMake variables:

  ARROW_BUILD_INTEGRATION="OFF"
  ARROW_BUILD_STATIC="OFF"
  ARROW_BUILD_TESTS="OFF"
  ARROW_EXTRA_ERROR_CONTEXT="ON"
  ARROW_WITH_RE2="OFF"
  ARROW_WITH_UTF8PROC="OFF"
  CMAKE_BUILD_TYPE="Debug"

您还可以从给定预设创建构建

$ mkdir build   # from inside the `cpp` subdirectory
$ cd build
$ cmake .. --preset ninja-debug-minimal
   Preset CMake variables:

     ARROW_BUILD_INTEGRATION="OFF"
     ARROW_BUILD_STATIC="OFF"
     ARROW_BUILD_TESTS="OFF"
     ARROW_EXTRA_ERROR_CONTEXT="ON"
     ARROW_WITH_RE2="OFF"
     ARROW_WITH_UTF8PROC="OFF"
     CMAKE_BUILD_TYPE="Debug"

   -- Building using CMake version: 3.21.3
   [ etc. ]

然后请求编译构建目标

$ cmake --build .
[142/142] Creating library symlink debug/libarrow.so.700 debug/libarrow.so

$ tree debug/
debug/
├── libarrow.so -> libarrow.so.700
├── libarrow.so.700 -> libarrow.so.700.0.0
└── libarrow.so.700.0.0

0 directories, 3 files

$ cmake --install .

创建构建时，可以传递除预设定义的选项之外的自定义选项，例如

$ cmake .. --preset ninja-debug-minimal -DCMAKE_INSTALL_PREFIX=/usr/local

注意

CMake 预设旨在帮助您开始 Arrow 开发并了解常见的构建配置。它们并非保证不变，将来可能会根据反馈进行更改。

建议强烈建议自动化构建、持续集成、发布脚本等使用手动配置，如下所述，而不是依赖 CMake 预设。

另请参阅

CMake 预设的官方文档.

手动配置#

构建系统默认使用 CMAKE_BUILD_TYPE=release，因此，如果省略此参数，则将生成发布构建。

注意

您需要设置更多选项才能在 Windows 上构建。有关详细信息，请参阅 在 Windows 上开发。

有多种构建类型可用

  • Debug：不应用任何编译器优化并在二进制文件中添加调试信息。

  • RelWithDebInfo：应用编译器优化，同时在二进制文件中添加调试信息。

  • Release：应用编译器优化并从二进制文件中删除调试信息。

注意

这些构建类型默认提供合适的优化/调试标志，但您可以通过指定 -DARROW_C_FLAGS_${BUILD_TYPE}=... 和/或 -DARROW_CXX_FLAGS_${BUILD_TYPE}=... 来更改它们。${BUILD_TYPE} 是构建类型的首字母大写。例如，DEBUG (-DARROW_C_FLAGS_DEBUG=... / -DARROW_CXX_FLAGS_DEBUG=...) 用于 Debug 构建类型，RELWITHDEBINFO (-DARROW_C_FLAGS_RELWITHDEBINFO=... / -DARROW_CXX_FLAGS_RELWITHDEBINFO=...) 用于 RelWithDebInfo 构建类型。

例如，您可以将 -O3 作为 Release 构建类型的优化标志，方法是传递 -DARROW_CXX_FLAGS_RELEASE=-O3 。您可以将 -g3 作为 Debug 构建类型的调试标志，方法是传递 -DARROW_CXX_FLAGS_DEBUG=-g3 。

您也可以使用标准的 CMAKE_C_FLAGS_${BUILD_TYPE} 和 CMAKE_CXX_FLAGS_${BUILD_TYPE} 变量，但建议使用 ARROW_C_FLAGS_${BUILD_TYPE} 和 ARROW_CXX_FLAGS_${BUILD_TYPE} 变量。CMAKE_C_FLAGS_${BUILD_TYPE} 和 CMAKE_CXX_FLAGS_${BUILD_TYPE} 变量会替换 CMake 提供的所有默认标志，而 ARROW_C_FLAGS_${BUILD_TYPE} 和 ARROW_CXX_FLAGS_${BUILD_TYPE} 只是附加指定的标志，从而可以选择性地覆盖某些默认值。

您还可以使用带有标志 -DARROW_EXTRA_ERROR_CONTEXT=ON 的默认构建，请参阅 额外的调试帮助。

最小发布构建（建议构建时使用 1GB 或更多 RAM）

$ mkdir build-release
$ cd build-release
$ cmake ..
$ make -j8       # if you have 8 CPU cores, otherwise adjust
$ make install

带有单元测试的最小调试构建（建议构建时使用 4GB 或更多 RAM）

$ git submodule update --init --recursive
$ export ARROW_TEST_DATA=$PWD/../testing/data
$ mkdir build-debug
$ cd build-debug
$ cmake -DCMAKE_BUILD_TYPE=Debug -DARROW_BUILD_TESTS=ON ..
$ make -j8       # if you have 8 CPU cores, otherwise adjust
$ make unittest  # to run the tests
$ make install

默认情况下不构建单元测试。构建后，还可以使用 CMake 提供的 ctest 工具调用单元测试（请注意，test 依赖于 python 的可用性）。

在某些 Linux 发行版上，运行测试套件可能需要设置显式区域设置。如果您看到任何与区域设置相关的错误，请尝试设置环境变量（这需要 locales 软件包或等效软件包）

$ export LC_ALL="en_US.UTF-8"

使用 Ninja 加速构建#

许多贡献者使用 Ninja 构建系统 来加快构建速度。它尤其可以加快增量构建的速度。要使用 ninja，在调用 cmake 时传递 -GNinja，然后使用 ninja 命令而不是 make。

统一构建#

CMake 的 统一构建 选项可以显著加快完整构建的速度，但也会增加内存需求。如果内存消耗不是问题，可以考虑启用它（使用 -DCMAKE_UNITY_BUILD=ON）。

可选组件#

默认情况下，C++ 构建系统会创建一个非常精简的构建。我们提供了一些可选的系统组件，可以通过传递布尔标志到 cmake 来选择构建。

  • -DARROW_BUILD_UTILITIES=ON：构建 Arrow 命令行工具

  • -DARROW_COMPUTE=ON：构建所有计算内核函数

  • -DARROW_CSV=ON：CSV 读取模块

  • -DARROW_CUDA=ON：CUDA 集成，用于 GPU 开发。依赖于 NVIDIA CUDA 工具包。可以通过使用 $CUDA_HOME 环境变量来自定义用于构建库的 CUDA 工具链。

  • -DARROW_DATASET=ON：数据集 API，隐含文件系统 API

  • -DARROW_FILESYSTEM=ON：文件系统 API，用于访问本地和远程文件系统

  • -DARROW_FLIGHT=ON：Arrow Flight RPC 系统，至少依赖于 gRPC

  • -DARROW_FLIGHT_SQL=ON：Arrow Flight SQL

  • -DARROW_GANDIVA=ON：Gandiva 表达式编译器，依赖于 LLVM、Protocol Buffers 和 re2

  • -DARROW_GANDIVA_JAVA=ON：Gandiva JNI 绑定，用于 Java

  • -DARROW_GCS=ON：构建支持 GCS 的 Arrow（需要 GCloud SDK for C++）

  • -DARROW_HDFS=ON：Arrow 与 libhdfs 集成，用于访问 Hadoop 文件系统

  • -DARROW_JEMALLOC=ON：构建基于 jemalloc 的 Arrow 分配器，默认启用

  • -DARROW_JSON=ON：JSON 读取模块

  • -DARROW_MIMALLOC=ON：构建基于 mimalloc 的 Arrow 分配器

  • -DARROW_ORC=ON：Arrow 与 Apache ORC 集成

  • -DARROW_PARQUET=ON：Apache Parquet 库和 Arrow 集成

  • -DPARQUET_REQUIRE_ENCRYPTION=ON：Parquet 模块化加密

  • -DARROW_PYTHON=ON：此选项已自 10.0.0 版起弃用。将在未来版本中移除。请改用 CMake 预设。或者您可以直接启用 ARROW_COMPUTE、ARROW_CSV、ARROW_DATASET、ARROW_FILESYSTEM、ARROW_HDFS 和 ARROW_JSON。

  • -DARROW_S3=ON：支持与 Amazon S3 兼容的文件系统

  • -DARROW_SUBSTRAIT=ON：构建对 Substrait 的支持

  • -DARROW_WITH_RE2=ON：构建对使用 re2 库的正则表达式的支持，默认启用，并在 ARROW_COMPUTE 或 ARROW_GANDIVA 为 ON 时使用

  • -DARROW_WITH_UTF8PROC=ON：构建对使用 utf8proc 库的 Unicode 属性的支持，默认启用，并在 ARROW_COMPUTE 或 ARROW_GANDIVA 为 ON 时使用

  • -DARROW_TENSORFLOW=ON：启用 TensorFlow 支持构建 Arrow

Arrow 中可用的压缩选项：

  • -DARROW_WITH_BROTLI=ON：构建对 Brotli 压缩的支持

  • -DARROW_WITH_BZ2=ON：构建对 BZ2 压缩的支持

  • -DARROW_WITH_LZ4=ON：构建对 lz4 压缩的支持

  • -DARROW_WITH_SNAPPY=ON：构建对 Snappy 压缩的支持

  • -DARROW_WITH_ZLIB=ON：构建对 zlib（gzip）压缩的支持

  • -DARROW_WITH_ZSTD=ON：构建对 ZSTD 压缩的支持

如果您的应用程序不需要核心 Arrow 共享库的某些功能，可以将其关闭以缩短构建时间。

  • -DARROW_IPC=ON：构建 IPC 扩展

注意

如果您的用例仅限于读取/写入 Arrow 数据，则默认选项就足够了。但是，如果您希望构建任何测试/基准测试，则还需要 ARROW_JSON（它将自动启用）。如果需要扩展格式支持，则添加 ARROW_PARQUET、ARROW_CSV、ARROW_JSON 或 ARROW_ORC 不应启用任何其他组件。

注意

通常，如果您预计使用任何超出 cast 的计算内核，最好启用 ARROW_COMPUTE。虽然（截至 12.0.0 版本）默认情况下内置了一些额外的内核，但此列表可能会在未来发生变化，因为它部分基于当前格式实现中的内核使用情况。

可选目标#

对于开发构建，您通常希望启用其他目标来测试您的更改，可以使用以下 cmake 选项。

  • -DARROW_BUILD_BENCHMARKS=ON：构建可执行基准测试。

  • -DARROW_BUILD_EXAMPLES=ON：构建使用 Arrow C++ API 的示例。

  • -DARROW_BUILD_INTEGRATION=ON：构建用于测试不同 Arrow 实现之间协议互操作性的其他可执行文件。

  • -DARROW_BUILD_UTILITIES=ON：构建可执行工具。

  • -DARROW_BUILD_TESTS=ON：构建可执行单元测试。

  • -DARROW_ENABLE_TIMING_TESTS=ON：如果构建单元测试，则启用依赖于挂钟时间的单元测试（此标志在 CI 上被禁用，因为它可能导致测试结果不稳定）。

  • -DARROW_FUZZING=ON：构建模糊测试目标和相关可执行文件。

可选检查#

以下特殊检查也可使用。它们以各种方式检测生成的代码，以便在运行时检测特定类的问题（例如，在执行单元测试时）。

  • -DARROW_USE_ASAN=ON：启用 Address Sanitizer 以检查内存泄漏、缓冲区溢出或其他类型的内存管理问题。

  • -DARROW_USE_TSAN=ON：启用 Thread Sanitizer 以检查多线程代码中的竞争条件。

  • -DARROW_USE_UBSAN=ON：启用 Undefined Behavior Sanitizer 以检查触发 C++ 未定义行为的情况。

其中一些选项是相互冲突的，因此如果您想使用所有选项，可能需要使用不同的选项构建多次。

CMake 版本要求#

我们支持 CMake 3.16 及更高版本。

LLVM 和 Clang 工具#

我们目前使用 LLVM 进行库构建以及其他开发者工具，例如使用 clang-format 进行代码格式化。LLVM 可以通过大多数现代包管理器（apt、yum、conda、Homebrew、vcpkg、chocolatey）安装。

构建依赖管理#

构建系统支持许多第三方依赖项。

  • AWSSDK：用于 S3 支持，需要系统 cURL，可以使用下面描述的 BUNDLED 方法

  • benchmark：Google benchmark，用于测试

  • Boost：用于跨平台支持

  • Brotli：用于数据压缩

  • BZip2：用于数据压缩

  • c-ares：gRPC 的依赖项

  • gflags：用于命令行工具（以前称为 Googleflags）

  • GLOG：用于日志记录

  • google_cloud_cpp_storage：用于 Google Cloud Storage 支持，需要系统 cURL，可以使用下面描述的 BUNDLED 方法

  • gRPC：用于远程过程调用

  • GTest：Googletest，用于测试

  • LLVM：Gandiva 的依赖项

  • Lz4：用于数据压缩

  • ORC：用于 Apache ORC 格式支持

  • re2：用于计算内核和 Gandiva，gRPC 的依赖项

  • Protobuf：Google Protocol Buffers，用于数据序列化

  • RapidJSON：用于数据序列化

  • Snappy：用于数据压缩

  • Thrift：Apache Thrift，用于数据序列化

  • utf8proc：用于计算内核

  • ZLIB：用于数据压缩

  • zstd：用于数据压缩

CMake 选项 ARROW_DEPENDENCY_SOURCE 是一个全局选项，指示构建系统如何解析每个依赖项。有几个选项：

  • AUTO：尝试在系统默认位置查找软件包，如果未找到则从源代码构建

  • BUNDLED：自动从源代码构建依赖项

  • SYSTEM：使用 CMake 内置的 find_package 函数在系统路径中查找依赖项，或者对于没有此功能的软件包使用 pkg-config

  • CONDA：使用 $CONDA_PREFIX 作为替代 SYSTEM PATH

  • VCPKG：查找由 vcpkg 安装的依赖项，如果未找到，则运行 vcpkg install 来安装它们

  • BREW：使用 Homebrew 默认路径作为替代 SYSTEM 路径

默认方法是 AUTO，除非您在活动的 conda 环境中开发（通过 $CONDA_PREFIX 环境变量的存在检测到），在这种情况下，它是 CONDA。

单个依赖项解析 #

虽然 -DARROW_DEPENDENCY_SOURCE=$SOURCE 为所有软件包设置全局默认值，但可以通过设置 -D$PACKAGE_NAME_SOURCE=.. 来覆盖单个软件包的解析策略。例如，要从源代码构建 Protocol Buffers，请设置：

-DProtobuf_SOURCE=BUNDLED

此变量不幸的是区分大小写；每个软件包使用的名称如上所列，但最新的列表可以在 cpp/cmake_modules/ThirdpartyToolchain.cmake 中找到。

捆绑的依赖项版本 #

当使用 BUNDLED 方法从源代码构建依赖项时，将使用 cpp/thirdparty/versions.txt 中的版本号。还有一个依赖项源下载器脚本（见下文），可用于设置脱机构建。

当使用 BUNDLED 进行依赖项解析时（如果您使用 jemalloc 或 mimalloc 分配器，这两种分配器是推荐的），在第三方项目中静态链接 Arrow 库会更复杂。有关如何在这种情况配置构建系统，请参阅下面的说明。

脱机构建 #

如果您不使用上述变量来指示 Arrow 构建系统使用预安装的依赖项，则 Arrow 构建系统将自动构建它们。每个依赖项的源代码存档将通过互联网下载，这可能会在网络访问受限的环境中导致问题。

要启用脱机构建，您可以自己下载源代码工件，并使用 ARROW_$LIBRARY_URL 形式的环境变量来指示构建系统从本地文件读取，而不是访问互联网。

为了让您更容易操作，我们准备了一个脚本 thirdparty/download_dependencies.sh，它会将每个依赖项的正确版本下载到您选择的目录中。它会在最后打印一系列 bash 风格的环境变量语句，供您的构建脚本使用。

# Download tarballs into $HOME/arrow-thirdparty
$ ./thirdparty/download_dependencies.sh $HOME/arrow-thirdparty

然后，您可以调用 CMake 来创建构建目录，它将使用声明的环境变量指向下载的存档，而不是下载它们（每个构建目录一个！）。

静态链接 #

当 -DARROW_BUILD_STATIC=ON 时，Arrow 构建系统构建的所有作为静态库的构建依赖项将合并在一起，以创建一个静态库 arrow_bundled_dependencies。在类 Unix 环境（Linux、macOS、MinGW）中，它称为 libarrow_bundled_dependencies.a，在使用 Visual Studio 的 Windows 上称为 arrow_bundled_dependencies.lib。此“依赖项包”库安装在与其他 Arrow 静态库相同的位置。

如果您使用 CMake，则如果您使用 arrow_static CMake 目标，则捆绑的依赖项将在链接时自动包含。在其他构建系统中，您可能需要显式链接到依赖项包。我们创建了一个 基于 CMake 的示例构建配置 来向您展示一个工作示例。

在 Linux 和 macOS 上，如果您的应用程序尚未链接到 pthread 库，则必须在链接器设置中包含 -pthread。在 CMake 中，这可以通过内置的 Threads 软件包来实现。

set(THREADS_PREFER_PTHREAD_FLAG ON)
find_package(Threads REQUIRED)
target_link_libraries(my_target PRIVATE Threads::Threads)

额外的调试帮助 #

如果您使用 CMake 选项 -DARROW_EXTRA_ERROR_CONTEXT=ON，它将使用额外的调试信息编译库，以检查 RETURN_NOT_OK 宏内的错误。在使用 ASSERT_OK 的单元测试中，这将产生如下错误输出：

../src/arrow/ipc/ipc-read-write-test.cc:609: Failure
Failed
../src/arrow/ipc/metadata-internal.cc:508 code: TypeToFlatbuffer(fbb, *field.type(), &children, &layout, &type_enum, dictionary_memo, &type_offset)
../src/arrow/ipc/metadata-internal.cc:598 code: FieldToFlatbuffer(fbb, *schema.field(i), dictionary_memo, &offset)
../src/arrow/ipc/metadata-internal.cc:651 code: SchemaToFlatbuffer(fbb, schema, dictionary_memo, &fb_schema)
../src/arrow/ipc/writer.cc:697 code: WriteSchemaMessage(schema_, dictionary_memo_, &schema_fb)
../src/arrow/ipc/writer.cc:730 code: WriteSchema()
../src/arrow/ipc/writer.cc:755 code: schema_writer.Write(&dictionaries_)
../src/arrow/ipc/writer.cc:778 code: CheckStarted()
../src/arrow/ipc/ipc-read-write-test.cc:574 code: writer->WriteRecordBatch(batch)
NotImplemented: Unable to convert type: decimal(19, 4)

弃用和 API 更改 #

我们使用宏 ARROW_DEPRECATED，它包装了 C++ 弃用属性，用于已弃用的 API。最好使用 -Werror=deprecated-declarations（对于 GCC/Clang 或其他编译器的类似标志）编译第三方应用程序，以主动捕获和解决 API 更改。

模块化构建目标 #

由于 C++ 项目有几个主要部分，因此我们提供了模块化 CMake 目标，用于构建每个库组件、单元测试和基准测试组及其依赖项

  • make arrow 用于 Arrow 核心库

  • make parquet 用于 Parquet 库

  • make gandiva 用于 Gandiva（LLVM 表达式编译器）库

注意

如果您已选择 Ninja 作为 CMake 生成器，请将 make arrow 替换为 ninja arrow，依此类推。

要构建单元测试或基准测试，请向目标名称添加 -tests 或 -benchmarks。因此 make arrow-tests 将构建 Arrow 核心单元测试。使用 -all 目标（例如 parquet-all）将构建所有内容。

如果您希望仅构建和安装一个或多个项目子组件，我们提供了 CMake 选项 ARROW_OPTIONAL_INSTALL 以仅安装已构建的目标。例如，如果您只想构建 Parquet 库、其测试及其依赖项，则可以运行：

cmake .. -DARROW_PARQUET=ON \
      -DARROW_OPTIONAL_INSTALL=ON \
      -DARROW_BUILD_TESTS=ON
make parquet
make install

如果您在调用 make 时省略了显式目标，则将构建所有目标。

在 macOS 上使用 Xcode 进行调试 #

Xcode 是 macOS 提供的 IDE，可用于通过生成 Xcode 项目来开发和调试 Arrow。

cd cpp
mkdir xcode-build
cd xcode-build
cmake .. -G Xcode -DARROW_BUILD_TESTS=ON -DCMAKE_BUILD_TYPE=DEBUG
open arrow.xcodeproj

这将生成一个项目并在 Xcode 应用中打开它。或者，命令 xcodebuild 将使用生成的项目执行命令行构建。建议在首次启动项目时使用“自动创建方案”选项。选择自动生成的方案将允许您构建并运行一个启用了断点的单元测试。

本页内容
在 GitHub 上编辑