企业官网建设流程全解析

• 数据工程
• 数据分析
• 大数据

Apache Arrow 的 R 语言接口（r/目录下的arrow包）在向 CRAN 提交新版本时，必须随源码包附带一份名为cran-comments.md的提交注释文件，向 CRAN 维护者说明「在哪些平台上完成过验证」以及「R CMD check的结果如何」。本文以仓库中的 cran-comments.md 为骨架，结合 PACKAGING.md 发布检查清单、Makefile 构建目标与 r_test.sh 中 CRAN 级检查的实现，逐段拆解这份文件的结构、每个测试环境的真实含义，以及 Arrow R 包提交 CRAN 前完整的质量门禁流程。读完本文，你将掌握如何解读、撰写并维护一份合格的 CRAN 提交注释，以及 Arrow R 包从构建到提交的完整检查链路。

一、cran-comments.md 是什么：CRAN 提交注释在 Arrow R 包中的角色

CRAN 要求每个提交的包在源码包根目录包含cran-comments.md，用于向 CRAN 维护者（volunteers）说明本次提交的验证情况。它通常包含两大部分：

1. Test environments：列出本次发布前运行R CMD check的操作系统、编译器与 R 版本组合；
2. R CMD check results：声明检查结果的 ERROR / WARNING / NOTE 情况，并对任何无法消除的 NOTE 给出解释。

Arrow 仓库中的 cran-comments.md 正是这一标准结构的真实范例。它位于r/目录下，与包描述文件 DESCRIPTION、发布清单 PACKAGING.md 同处一地，是 R 包发布流程的「最后一公里」产物——只有当 PACKAGING.md 中列出的所有检查步骤全部通过后，这份注释才会随arrow_X.X.X.tar.gz一起上传到 CRAN 提交页面。

二、Test environments 部分逐行解析

原文完整列出的测试环境如下：

* Debian Linux, GCC, R-devel/R-patched/R-release * Fedora Linux, GCC/clang, R-devel * Ubuntu Linux 16.04 LTS, R-release, GCC * win-builder (R-devel and R-release) * macOS 10.14, R-oldrel

2.1 为什么必须声明测试环境

CRAN 维护者会对照这份清单核验提交者是否覆盖了足够多的平台组合。R 生态中一个共识是：只有在多个操作系统、编译器、R 版本上都能通过R CMD check的包才适合进入 CRAN。Arrow 作为同时绑定 C++ 原生库的包（详见下文），对编译器差异、链接行为尤其敏感，因此环境矩阵的覆盖度直接关系到提交能否被接受。

2.2 R 版本分支的含义

清单中的R-devel、R-patched、R-release、R-oldrel是 R 官方定义的四个版本分支，含义固定：

Arrow 的覆盖策略是：在 Debian 上同时跑R-devel/R-patched/R-release三个分支（GCC 编译器），在 Fedora 上跑R-devel（并同时用 GCC 和 clang 两种编译器），在 Ubuntu LTS 上跑R-release，在 macOS 上跑R-oldrel。这样组合出「新版本 R + 老版本 R」「GCC + clang」「Linux + Windows + macOS」三个维度的交叉覆盖。

2.3 平台与编译器的分工

• Debian Linux + GCC：Linux 上的主测试平台，覆盖三个 R 版本分支，是环境矩阵的中坚；
• Fedora Linux + GCC/clang：额外引入 clang 编译器，用于捕获 GCC 与 clang 在 C++ 编译（如模板实例化、告警级别）上的差异——这对 Arrow 这种大量使用 C++17 模板与表达式求值引擎的包尤为重要；
• Ubuntu 16.04 LTS + R-release + GCC：覆盖长期支持版 LTS 发行版，贴近多数生产服务器环境；
• win-builder (R-devel and R-release)：win-builder 是 CRAN 官方提供的 Windows 远程检查服务（通过上传*.tar.gz触发），用于在 Windows 工具链（Rtools）上验证R CMD check，是必须的一环；
• macOS 10.14 + R-oldrel：覆盖 Apple 平台的旧版本 R，验证与 macOS 系统库的链接兼容性。

需要说明：原文中的 Ubuntu 16.04 与 macOS 10.14 是这份文件撰写时使用的具体发行版版本号，属于历史记录；当前仓库的 CI 环境以 Docker 镜像形式维护于 ci/docker/（如ubuntu-22.04-cpp.dockerfile、fedora-39-cpp.dockerfile等），发布前应依据当时实际使用的环境更新此清单。

三、R CMD check results 部分逐行解析

原文的检查结果声明只有一句话，但信息量不小：

There were no ERRORs or WARNINGs. On some platforms, there is a NOTE about the installed package size.

3.1 R CMD check 的三级结果

R CMD check对包进行检查后输出三个级别的结论，CRAN 的容忍度完全不同：

Arrow 的目标是 ERROR 与 WARNING 全平台清零，NOTE 则逐条说明。

3.2 「installed package size」NOTE 的根源

这个 NOTE 的产生与 Arrow R 包的架构直接相关。arrow并非纯 R 包：它通过 cpp11 绑定 Arrow C++ 库，并且为了在未安装系统级 libarrow 的环境上也能编译安装，发布流程会把 C++ 源码内嵌进 R 包。

证据在 Makefile 的sync-cpp目标中：

sync-cpp: cp ../NOTICE.txt inst/NOTICE.txt rsync --archive --delete --exclude 'apidoc' --exclude 'build' --exclude ... ../cpp tools/ cp -p ../.env tools/dotenv ...

它把仓库根目录的 cpp/ 同步到tools/cpp/（仅保留源码与构建所需部分，剔除src/gandiva、src/jni、测试文件等），再由 PACKAGING.md 中的make build步骤「copies Arrow C++ into tools/cpp, prunes some unnecessary components, and runsR CMD build」。因此最终生成的arrow_X.X.X.tar.gz携带整套 C++ 源码，安装包体积远超普通 R 包，CRAN 便会给出「package size」NOTE。这正是注释中「on some platforms, there is a NOTE」需要主动说明的原因——体积大是设计使然，而非打包失误。

3.3 如何确认 NOTE 的合理性

发布前可通过 r/tools/check-versions.R 与 r/tools/nixlibs.R 中的逻辑核对内嵌 C++ 库版本与包版本的一致性（nixlibs.R甚至会在未匹配到预期 nightly 版本时回退到源码构建并输出日志），确保体积增长可解释、可复现。

四、Arrow R 包提交 CRAN 前的完整检查链路

cran-comments.md是检查链路的终点产物，其前提是 PACKAGING.md 中一整套清单全部落实。以下按执行顺序梳理关键环节。

4.1 本地构建与检查：make build / make check / make release

仓库 r/Makefile 提供了三个逐级递进的入口：

build: doc sync-cpp R CMD build ${args} . check: build -export _R_CHECK_CRAN_INCOMING_REMOTE_=FALSE && export ARROW_R_DEV=$(ARROW_R_DEV) && export _R_CHECK_TESTS_NLINES_=0 && R CMD check --as-cran arrow_$(VERSION).tar.gz release: build -export _R_CHECK_TESTS_NLINES_=0 && R CMD check --as-cran arrow_$(VERSION).tar.gz

• make build：先执行doc（roxygen 文档重生成）与sync-cpp（内嵌 C++ 源码），再R CMD build生成源码包arrow_$(VERSION).tar.gz；
• make check：对生成的包执行R CMD check --as-cran，并关闭_R_CHECK_CRAN_INCOMING_REMOTE_（避免远程 URL 检查拖慢/误报）；--as-cran是 CRAN 官方推荐的最严格检查模式，等价于尽量模拟 CRAN 的检查环境；
• make release：面向最终发布版，同样以--as-cran检查但保留远程检查项。

注意check目标设置ARROW_R_DEV=$(ARROW_R_DEV)（默认"TRUE"）。ARROW_R_DEV在 Arrow R 包开发中会启用data-raw/codegen.R的代码生成逻辑与额外的编译告警豁免，具体可参考 workflow.Rmd 中「C++ code」一节的说明。

4.2 devtools::check_built 与反向依赖检查

PACKAGING.md 要求在 release candidate 切出后：

devtools::check_built("arrow_X.X.X.tar.gz")

对构建产物直接执行完整检查；同时通过archery docker run r-revdepcheck运行反向依赖（reverse dependency）检查，评估依赖 arrow 的上游包是否会因本次发布而破坏——这对应 cran-comments.md 中「所有平台无 ERROR/WARNING」这一声明的支撑证据。

4.3 win-builder 与 MacBuilder 的外部验证

清单要求将生成的.tar.gz上传到 win-builder（r-devel）与 MacBuilder，确认 Windows 与 macOS 上的检查干净后才可提交。这也解释了cran-comments.md环境清单中win-builder (R-devel and R-release)一行的由来——它不是口头声明，而是有实际上传验证记录的。

4.4 CI 中 CRAN 级检查的实现：r_test.sh

仓库 CI 通过 r_test.sh 复刻 CRAN 检查行为，其中关键的环境变量设置完整对应「模拟 CRAN」的目标：

export _R_CHECK_CRAN_INCOMING_REMOTE_=FALSE export _R_CHECK_DONTTEST_EXAMPLES_=TRUE export _R_CHECK_FORCE_SUGGESTS_=FALSE export _R_CHECK_LIMIT_CORES_=FALSE export _R_CHECK_TESTS_NLINES_=0 export _R_CHECK_STOP_ON_INVALID_NUMERIC_VERSION_INPUTS_=TRUE

• _R_CHECK_DONTTEST_EXAMPLES_=TRUE：强制执行文档中\donttest示例（R ≥ 4.0 的行为）；
• _R_CHECK_FORCE_SUGGESTS_=FALSE：Suggests 依赖未安装时允许继续（Arrow 的 Suggests 列表很长，见 DESCRIPTION）；
• _R_CHECK_STOP_ON_INVALID_NUMERIC_VERSION_INPUTS_=TRUE：将非法版本号输入由告警升级为错误，确保发布前暴露。

随后脚本内嵌的 R 代码通过rcmdcheck::rcmdcheck(build_args = ..., args = c('--as-cran', ...), error_on = 'warning')执行检查，只要出现 warning 即判定失败——这与cran-comments.md中「no ERRORs or WARNINGs」的声明完全一致。

另外，脚本通过NOT_CRAN环境变量区分两种模式：

as_cran <- !identical(tolower(Sys.getenv('NOT_CRAN')), 'true') if (as_cran) { args <- '--as-cran' } else { args <- c('--no-manual', '--ignore-vignettes') }

NOT_CRAN=true（默认开发模式）表示非 CRAN 环境，跳过手册构建、跳过 vignette；NOT_CRAN为空时则以--as-cran全量模式运行，模拟 CRAN 的严格检查。

4.5 提交前的最后动作

按 PACKAGING.md 的「CRAN submission」清单：

1. 移除 README 中的 badge（避免 URL 检查误报）；
2. 运行urlchecker::url_check()校验文档链接；
3. 执行Rscript tools/update-checksums.R <libarrow version>下载预编译二进制校验和到tools/目录；
4. 重新生成arrow_X.X.X.tar.gz（make build）；
5. 上传至 CRAN 提交页面并确认提交邮件。

五、为 Arrow R 包维护 cran-comments.md 的实操建议

结合以上分析，当需要更新 cran-comments.md 时，可按如下清单核对：

1. 环境矩阵与事实对齐：对照 CI 与本地实际运行R CMD check --as-cran的平台（Debian/Fedora/Ubuntu 的 Docker 镜像见 ci/docker/，Windows 见 win-builder 结果邮件），逐条更新「Test environments」；
2. R 分支覆盖完整：确认R-devel、R-patched、R-release均有覆盖（macOS 侧可用R-oldrel补齐旧版本维度）；
3. 结果声明准确：ERROR/WARNING 必须为 0；任何 NOTE 都必须在注释中解释原因；
4. NOTE 解释可溯源：例如「installed package size」需说明体积来自内嵌的 Arrow C++ 库（Makefile 的sync-cpp目标），并确保tools/cpp的同步与版本校验（nixlibs.R、check-versions.R）均已通过；
5. 与发布清单联动：cran-comments.md的最终版本应在 PACKAGING.md 全部清单完成、make release检查通过后定稿，避免声明与实际检查结果脱节。

六、小结

cran-comments.md虽然只有寥寥数行，却是 Apache Arrow R 包质量门禁的「对外公示」。其背后是 PACKAGING.md 数十项检查、Makefile 的build/check/release目标、r_test.sh 中以--as-cran为核心的严格检查实现，以及 win-builder/MacBuilder 的外部验证。理解了这份文件的结构与每个字段的出处，就掌握了 Arrow R 包从源码到 CRAN 的完整验证链路——无论你是要参与 Arrow R 包的发布，还是维护自己的 R 包提交，这份「测试环境矩阵 + 检查结果声明」的范式都值得直接复用。

• 数据工程
• 数据分析
• 大数据