跳过内容

开发者工作流

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

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

  • 用于代码风格规范的 air
  • 用于代码分析的 lintr
  • 用于构建网站的 pkgdown
  • 用于软件包文档编写的 roxygen2
    • R 文档使用了 roxygen2 7.1.2 版本中引入的 @examplesIf 标签

安装 air 的说明可在 https://posit-dev.github.io/air/cli.html 找到。

你可以通过运行以下命令安装所有其他额外的依赖项

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

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

加载 arrow

你可以通过 devtools::load_all() 加载该 R 软件包。

重建文档

R 文档使用了 roxygen2 7.1.2 版本中引入的 @examplesIf 标签。

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)

代码风格与静态检查

代码风格与静态检查可以完全通过 pre-commit 工具进行设置和执行

pre-commit run --show-diff-on-failure --color=always --all-files r

有关 R 和 C++ 代码风格与检查细节，请参阅以下小节。

R 代码

软件包中的 R 代码遵循 tidyverse 风格。在提交拉取请求（PR）及推送时，我们的持续集成（CI）系统会运行静态检查，并在 PR 中通过注释标记出可能的错误。

你可以使用 air 格式化工具自动更改软件包中的代码格式。

air 格式化工具可以修复许多风格错误，不过并非所有的 lintr 错误都能通过 air 自动修复。我们刻意不对其应用风格规范的文件列表列在 r/air.toml 的 exclude 字段中。

如上所述，使用 pre-commit 进行静态检查和格式化是确保你的更改得到正确检查的最佳方式，但如果你愿意，也可以从仓库的 arrow/r 目录中单独运行这些工具。

在命令行中，运行 air

air format

在 R 中，运行 lintr

lintr::lint_package()

注意：要运行 lintr，我们要求先安装 cyclocomp 软件包。

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。安装并启用相应的插件可以为你省去很多麻烦。

运行测试

测试既可以使用 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，否则某些测试会被禁用。

  • 除非设置了 ARROW_LARGE_MEMORY_TESTS=true，否则需要分配超过 2GB 内存来测试大型类型的测试将被禁用。

  • 除非在 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}

有关匹配下方 tasks: 列表中项名称的通配符表达式模式列表，请参阅 crossbow 配置开头附近的 r: 组定义。