开发指南#

本节为希望为 C++ 代码库贡献的开发者提供信息。

注意

由于项目的大部分开发者在 Linux 或 macOS 上工作，因此并非所有功能或开发工具都在 Windows 上得到统一支持。如果您使用 Windows，请参阅在 Windows 上开发。

编译器警告级别#

BUILD_WARNING_LEVEL CMake 选项可在我们用于代码整洁的预设编译器警告级别集之间切换。对于发布版本，默认警告级别为 PRODUCTION，而对于调试版本，默认级别为 CHECKIN。

当调试版本使用 CHECKIN 时，如果使用 gcc 和 clang，则会添加 -Werror，导致任何警告都会使构建失败；如果使用 MSVC，则设置 /WX，效果相同。

运行单元测试#

-DARROW_BUILD_TESTS=ON CMake 选项启用单元测试可执行文件的构建。然后，您可以单独运行它们，方法是启动所需的可执行文件；或者通过启动 ctest 可执行文件（CMake 套件的一部分）一次性运行所有测试。

一个可能的调用是这样的

$ ctest -j16 --output-on-failure

其中 -j16 选项并行运行最多 16 个测试，利用了多个 CPU 内核和硬件线程。

运行基准测试#

-DARROW_BUILD_BENCHMARKS=ON CMake 选项启用基准测试可执行文件的构建。然后，您可以通过从命令行启动相应的可执行文件来单独运行基准测试，例如

$ ./build/release/arrow-builder-benchmark

注意

为了获得有意义的基准测试结果，强烈建议在 Release 模式下构建，以启用编译器优化。

代码风格、Linting 和 CI#

本项目遵循 Google C++ 风格指南，但有以下例外

  • 我们将行长度限制放宽到 90 个字符。

  • 我们在头文件中使用 NULLPTR 宏（而不是 nullptr），该宏定义在 src/arrow/util/macros.h 中，以支持构建 C++/CLI (ARROW-1134)。

  • 我们放宽了指南中关于结构体的规则。对于公共头文件，我们应仅将结构体用于主要为简单数据容器的对象，这些对象可以公开所有内部成员，并且任何方法主要是为了方便。对于私有头文件，规则进一步放宽，结构体可以在方便时用于不需要访问控制的类型，即使它们可能不是简单的数据容器。

  • 我们更喜欢使用指针作为输出和输入/输出参数（风格指南在某些情况下推荐可变引用）。

我们在 GitHub Actions 上进行的持续集成构建会在各种平台和配置上运行单元测试套件，包括使用 Address Sanitizer 和 Undefined Behavior Sanitizer 来检查各种行为不当模式，例如内存泄漏。此外，代码库还接受多项代码风格和代码整洁性检查。

为了通过 CI 构建，您修改后的 Git 分支必须通过以下检查

  • 使用项目活动版本的 clang 构建 C++，且在 -DBUILD_WARNING_LEVEL=CHECKIN 的情况下没有编译器警告。请注意，有些类别的警告（例如 -Wdocumentation，详见下文）不会被 gcc 捕获。

  • 通过运行 pre-commit run --show-diff-on-failure --color=always --all-files cpp 通过各种 C++（和其他）风格检查。

在拉取请求上，“Dev / Lint”管道将运行这些检查，并报告需要修复的文件/行（如果有）。

检查 ABI 和 API 稳定性#

要构建 ABI 合规性报告，您需要安装两个工具：abi-dumper 和 abi-compliance-checker。

在调试模式下构建 Arrow C++，或者您可以使用 -Og，它也会构建必要的符号但包含一些代码优化。构建完成后，您可以使用以下命令生成 ABI 报告：

abi-dumper -lver 9 debug/libarrow.so -o ABI-9.dump

上述版本号可随意选择。由于我们希望比较版本，您现在应该 git checkout 您想要比较的版本，并使用不同的版本号重新运行上述命令。生成两个报告后，您可以使用以下命令构建比较报告：

abi-compliance-checker -l libarrow -d1 ABI-PY-9.dump -d2 ABI-PY-10.dump

报告将以 HTML 格式生成在 compat_reports/libarrow 中。

API 文档#

我们在头文件中使用 Doxygen 风格注释 (///) 来表示我们希望在类和函数的 API 文档中显示的注释。

当使用 clang 并使用 -DBUILD_WARNING_LEVEL=CHECKIN 构建时，会使用 -Wdocumentation 标志，该标志检查一些常见的文档不一致性，例如使用 \param 记录了部分而不是所有函数参数。有关此内容的更多信息，请参阅 LLVM 文档警告部分。

虽然我们将 API 文档作为基于 Sphinx 的主文档站点的一部分发布，但您也可以随时使用 Doxygen 构建 C++ API 文档。从 cpp/apidoc 目录运行以下命令：

doxygen Doxyfile

这需要安装 Doxygen。

Apache Parquet 开发#

要为 Apache Parquet 构建 C++ 库，请在调用 CMake 时添加标志 -DARROW_PARQUET=ON。要构建支持加密的 Apache Parquet，请在调用 CMake 时添加标志 -DPARQUET_REQUIRE_ENCRYPTION=ON。Parquet 库和单元测试可以使用 parquet make 目标构建

make parquet

在 Linux 和 macOS 上，如果您的系统未安装 Apache Thrift，或者您正在使用 -DThrift_SOURCE=BUNDLED 构建，则必须安装 bison 和 flex 包。在 Windows 上，我们会在从源代码构建 Thrift 时自动处理这些构建依赖项。

运行 ctest -L unittest 将运行所有已构建的 C++ 单元测试，而 ctest -L parquet 将仅运行 Parquet 单元测试。单元测试依赖于环境变量 PARQUET_TEST_DATA，该变量依赖于到 apache/parquet-testing 仓库的 git 子模块

git submodule update --init
export PARQUET_TEST_DATA=$ARROW_ROOT/cpp/submodules/parquet-testing/data

这里 $ARROW_ROOT 是 Arrow 代码库的绝对路径。

Arrow Flight RPC#

除了 Arrow 依赖项之外，Flight 还需要

  • gRPC（>= 1.14，大致）

  • Protobuf（>= 3.6，早期版本可能有效）

  • c-ares（gRPC 使用）

默认情况下，Arrow 在构建 Flight 时会尝试下载并构建这些依赖项。

可选的 flight 库和测试可以通过传递 -DARROW_FLIGHT=ON 来构建。

cmake .. -DARROW_FLIGHT=ON -DARROW_BUILD_TESTS=ON
make

您也可以使用已有的额外依赖项安装。构建时，设置环境变量 gRPC_ROOT 和/或 Protobuf_ROOT 和/或 c-ares_ROOT。

我们正在针对 gRPC 的最新版本和版本进行开发。https://forge.conda.org.cn/ 提供的 libgrpc 包是跨平台获取 gRPC 的可靠方法之一。您可以尝试使用 gRPC 和 Protobuf 的系统库，但这些库可能太旧。在 macOS 上，您可以尝试 Homebrew

brew install grpc