跳转到内容

开发者工作流程

来源：vignettes/developers/workflow.Rmd
workflow.Rmd

Arrow R 包使用多种额外的开发工具

  • 使用 lintr 进行代码分析
  • 使用 styler 进行代码样式检查
  • 使用 pkgdown 构建网站
  • 使用 roxygen2 为包生成文档
    • R 文档使用 @examplesIf 标签，该标签在 roxygen2 7.1.2 版本中引入

您可以通过运行以下命令安装所有这些额外的依赖项

install.packages(c("lintr", "styler", "pkgdown", "roxygen2"))

arrow/r 目录包含一个 Makefile，可帮助您从命令行执行一些常见任务（例如 make test、make doc、make clean 等）。

加载 arrow

您可以通过 devtools::load_all() 加载 R 包。

重新构建文档

R 文档使用 @examplesIf 标签，该标签在 roxygen2 7.1.2 版本中引入。

remotes::install_github("r-lib/roxygen2")

您可以使用 devtools::document() 和 pkgdown::build_site() 重新构建文档并预览结果。

# Update roxygen documentation
devtools::document()

# To preview the documentation website
pkgdown::build_site(preview=TRUE)

样式和代码检查

R 代码

包中的 R 代码遵循 tidyverse 样式。在提交 PR 时（以及推送时），我们的 CI 将运行代码检查，并使用注释在拉取请求上标记可能的错误。

要在本地运行代码检查器，请安装 lintr 包（请注意，我们目前使用的是一个包含尚未被上游接受的修复程序的分支，请参阅文件 ci/docker/linux-apt-lint.dockerfile 中 lintr 的安装方式以了解当前状态），然后运行

lintr::lint_package("arrow/r")

您可以使用 styler 包自动更改包中代码的格式。 有两种方法可以做到这一点

  1. 使用评论机器人通过在 PR 上运行命令 @github-actions autotune 自动执行此操作，并将其提交回分支。

  2. 通过 Makefile 命令在本地运行 styler

make style # (for only the files changed)
make style-all # (for all files)

或在 R 中运行

# note the file that should not be styled
styler::style_pkg(exclude_files = c("data-raw/codegen.R"))

styler 包将修复许多样式错误，但并非所有 lintr 错误都可以通过 styler 自动修复。 我们有意不设置样式的文件列表位于 r/.styler_excludes.R 中。

C++ 代码

arrow 包在 cpp11 之上使用了一些定制工具来准备其位于 src/ 中的 C++ 代码。这是因为某些功能仅在构建期间有条件地启用和构建。如果您更改 R 包中的 C++ 代码，则需要将 ARROW_R_DEV 环境变量设置为 true（或者，将其添加到您的 ~/.Renviron 文件中以使其在会话之间持久化），以便将 data-raw/codegen.R 文件用于代码生成。 Makefile 命令也会自动处理此问题。

我们在 C++ 代码中使用 Google C++ 样式。 实现此目的的最简单方法是使用可为您格式化代码的编辑器/IDE。许多流行的编辑器/IDE 都支持在保存 C++ 文件时运行 clang-format。安装/启用相应的插件可以为您省去很多麻烦。

使用以下命令检查样式错误

./lint.sh

在提交之前使用以下命令修复任何样式问题

./lint.sh --fix

lint 脚本需要 Python 3 和 clang-format。如果找不到该命令，您可以显式提供其路径，例如

CLANG_FORMAT=/opt/llvm/bin/clang-format ./lint.sh

您可以使用以下命令查看所需的 clang-format 版本

(. ../.env && echo ${CLANG_TOOLS})

_注意_ lint 脚本需要 Python 3 和 Python 依赖项（请注意，`cmake_format 已固定到特定版本）

  • autopep8
  • flake8
  • cmake_format==0.5.2

运行测试

可以使用 devtools::test() 或 Makefile 替代方案运行测试。

# Run the test suite, optionally filtering file names
devtools::test(filter="^regexp$")
# or the Makefile alternative from the arrow/r directory in a shell:
make test file=regexp

某些测试会根据包构建中某些功能的可用性（S3 支持、压缩库等）有条件地启用。其他测试通常默认跳过，但可以使用环境变量或其他设置启用

  • 如果包在没有 C++ libarrow 的情况下构建，则在 Linux 上将跳过所有测试。要使构建在 libarrow 不可用时失败（即，测试 C++ 构建是否成功），请设置 TEST_R_WITH_ARROW=true

  • 除非 ARROW_R_DEV=true，否则某些测试将被禁用

  • 需要分配大于 2GB 的内存来测试大型类型的测试将被禁用，除非 ARROW_LARGE_MEMORY_TESTS=true

  • 除非在 AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY 中设置了凭据，否则针对真实 S3 存储桶的集成测试将被禁用；可以根据请求提供这些凭据

  • 如果发现 minio server 进程正在运行，则将启用在本地使用 MinIO 的 S3 测试。如果您使用自定义设置运行 MinIO，可以设置 MINIO_ACCESS_KEY、MINIO_SECRET_KEY 和 MINIO_PORT 来覆盖默认值。

运行检查

您可以使用 devtools::check() 运行包检查，并使用 covr::package_coverage() 检查测试覆盖率。

# All package checks
devtools::check()

# See test coverage statistics
covr::report()
covr::package_coverage()

要进行完整的包验证，您可以从终端运行以下命令。

R CMD build .
R CMD check arrow_*.tar.gz --as-cran

运行扩展 CI 检查

在拉取请求中，您可以通过对 PR 进行评论来触发某些操作。这些扩展的 CI 检查每晚运行，也可以使用名为 crossbow 的内部工具按需请求。 下面显示了一些重要的 GitHub 评论命令。

运行所有扩展的 R CI 任务

@github-actions crossbow submit -g r

这将运行每个与 R 相关的 CI 任务。

运行特定任务

@github-actions crossbow submit {task-name}

请参阅 crossbow 配置 开头附近的 r: 组定义，以获取与下方 tasks: 列表中项目名称匹配的 glob 表达式模式列表。

运行代码检查和文档构建任务

@github-actions autotune

这将运行并修复 lint C++ 代码检查错误，运行 R 文档（以及其他清理任务），对任何更改的 R 代码运行 styler，并将结果更新提交到分支。