开发指南#

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

注意

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

编译器警告级别#

CMake 选项 BUILD_WARNING_LEVEL 用于切换我们用于代码整洁的预定义编译器警告级别集。对于发布构建，默认警告级别为 PRODUCTION，而对于调试构建，默认警告级别为 CHECKIN。

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

运行单元测试#

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

可能的调用示例如下

$ ctest -j16 --output-on-failure

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

运行基准测试#

CMake 选项 -DARROW_BUILD_BENCHMARKS=ON 可以构建基准测试可执行文件。然后，您可以通过命令行单独运行基准测试，例如：

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

注意

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

代码风格、静态分析和 CI#

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

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

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

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

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

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

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

  • C++ 使用项目当前活跃版本的 clang 构建，且在 -DBUILD_WARNING_LEVEL=CHECKIN 模式下没有编译器警告。请注意，有些类别的警告（例如 -Wdocumentation，详情见下文）是 gcc 无法捕获的。

  • 通过各种 C++（及其他）风格检查，使用 Archery 的 lint 子命令进行检查。也可以通过在本地运行 archery lint --cpplint --clang-format --clang-tidy --fix 来修复这些问题。

  • CMake 文件通过风格检查，可以通过运行 archery lint --cmake-format --fix 来修复。这需要 Python 3 和 cmake_format（注意：这目前在 Windows 上不起作用）。

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

为了考虑到 LLVM 主要版本之间 clang-format 行为的差异，我们锁定了使用的 clang-format 版本。您可以通过在 .env 文件中查找 CLANG_TOOLS 变量的值来确认当前锁定的版本。请注意，版本必须完全匹配；更新的版本（即使是补丁版本）也无法工作。LLVM 可以通过系统包管理器或像 Conda 或 Homebrew 这样的包管理器安装，但请注意，它们可能无法提供所需的精确版本。或者，可以直接从 LLVM 网站下载二进制文件。

为方便起见，除了 Archery 之外，还可以通过构建来运行 C++ 风格检查。为此，构建一个或多个目标 format（用于 clang-format）、lint_cpp_cli、lint（用于 cpplint）或 clang-tidy。例如：

$ cmake -GNinja ../cpp ...
$ ninja format lint clang-tidy lint_cpp_cli

根据您安装 clang-format 的方式，构建系统可能找不到它。在这种情况下，调用 CMake 将显示如下错误：

-- clang-format 12 not found

或者如果安装了错误的版本

-- clang-format found, but version did not match "^clang-format version 12"

您可以使用环境变量 $CLANG_TOOLS_PATH 提供包含 clang-format 可执行文件及其他文件的目录的显式路径，或者在调用 CMake 时传递 -DClangTools_PATH=$PATH_TO_CLANG_TOOLS。例如：

# We unpacked LLVM here:
$ ~/tools/bin/clang-format --version
clang-format version 12.0.0
# Pass the directory containing the tools to CMake
$ cmake ../cpp -DClangTools_PATH=~/tools/bin/
...snip...
-- clang-tidy found at /home/user/tools/bin/clang-tidy
-- clang-format found at /home/user/tools/bin/clang-format
...snip...

为了使静态分析对每个人来说更具可复现性，我们提供了一个 docker compose 目标，可以在仓库根目录执行：

$ docker compose run ubuntu-lint

或者，在开放的拉取请求上，评论机器人可以为您格式化 C++ 代码（它会将提交推送到分支，然后您可以拉取）。只需评论以下内容：

@github-actions autotune

使用 include-what-you-use (IWYU) 清理头文件引用#

我们偶尔使用 Google 的 include-what-you-use 工具，也称为 IWYU，来移除不必要的引用。

要开始使用 IWYU，您必须首先按照项目文档中的说明构建它。一旦 include-what-you-use 可执行文件位于您的 $PATH 中，您必须在新的 out-of-source CMake 构建目录中运行带有 -DCMAKE_EXPORT_COMPILE_COMMANDS=ON 的 CMake，如下所示：

mkdir -p $ARROW_ROOT/cpp/iwyu
cd $ARROW_ROOT/cpp/iwyu
cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \
  -DARROW_BUILD_BENCHMARKS=ON \
  -DARROW_BUILD_BENCHMARKS_REFERENCE=ON \
  -DARROW_BUILD_TESTS=ON \
  -DARROW_BUILD_UTILITIES=ON \
  -DARROW_COMPUTE=ON \
  -DARROW_CSV=ON \
  -DARROW_DATASET=ON \
  -DARROW_FILESYSTEM=ON \
  -DARROW_FLIGHT=ON \
  -DARROW_GANDIVA=ON \
  -DARROW_HDFS=ON \
  -DARROW_JSON=ON \
  -DARROW_PARQUET=ON \
  -DARROW_S3=ON \
  -DARROW_WITH_BROTLI=ON \
  -DARROW_WITH_BZ2=ON \
  -DARROW_WITH_LZ4=ON \
  -DARROW_WITH_SNAPPY=ON \
  -DARROW_WITH_ZLIB=ON \
  -DARROW_WITH_ZSTD=ON \
  ..

为了让 IWYU 在代码库中的所需组件上运行，必须通过 CMake 配置标志启用它。完成此操作后，您可以通过运行辅助脚本 iwyu.sh 在整个代码库上运行 IWYU：

IWYU_SH=$ARROW_ROOT/cpp/build-support/iwyu/iwyu.sh
./$IWYU_SH

由于这非常耗时，您可以使用特殊的“match”选项检查匹配某些字符串模式的文件子集：

./$IWYU_SH match $PATTERN

例如，如果您想对 src/arrow/array 中的所有文件进行 IWYU 检查，您可以运行：

./$IWYU_SH match arrow/array

检查 ABI 和 API 稳定性#

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

在 Debug 模式下构建 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

报告随后会生成在 compat_reports/libarrow 目录中，格式为 HTML。

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 make 目标构建 Parquet 库和单元测试：

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 submodule。

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 时会尝试下载并构建这些依赖项。

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

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

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

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

brew install grpc