Add Rcpp Integration

添加 Rcpp 集成

使用 Rcpp 将 C++ 代码集成到 R 包中，用于性能关键操作。

适用场景

• R 函数过慢且性能分析确认存在瓶颈
• 需要与现有 C/C++ 库交互
• 实现受益于编译代码的算法（循环、递归）
• 添加 RcppArmadillo 用于线性代数操作

输入

• 必需：现有 R 包
• 必需：需要用 C++ 替换或增强的 R 函数
• 可选：要交互的外部 C++ 库
• 可选：是否使用 RcppArmadillo（默认：纯 Rcpp）

步骤

第 1 步：设置 Rcpp 基础设施

usethis::use_rcpp()

此操作会：

• 创建 src/ 目录
• 在 DESCRIPTION 中将 Rcpp 添加到 LinkingTo 和 Imports
• 创建包含 @useDynLib 和 @importFrom Rcpp sourceCpp 的 R/packagename-package.R
• 更新 .gitignore 以排除编译文件

对于 RcppArmadillo：

usethis::use_rcpp_armadillo()

预期结果： src/ 目录已创建，DESCRIPTION 中 Rcpp 已添加到 LinkingTo 和 Imports，R/packagename-package.R 包含 @useDynLib 指令。

失败处理： 如果 usethis::use_rcpp() 失败，手动创建 src/，在 DESCRIPTION 中添加 LinkingTo: Rcpp 和 Imports: Rcpp，并在包级文档文件中添加 #' @useDynLib packagename, .registration = TRUE 和 #' @importFrom Rcpp sourceCpp。

第 2 步：编写 C++ 函数

创建 src/my_function.cpp：

#include <Rcpp.h>
using namespace Rcpp;

//' Compute cumulative sum efficiently
//'
//' @param x A numeric vector
//' @return A numeric vector of cumulative sums
//' @export
// [[Rcpp::export]]
NumericVector cumsum_cpp(NumericVector x) {
  int n = x.size();
  NumericVector out(n);
  out[0] = x[0];
  for (int i = 1; i < n; i++) {
    out[i] = out[i - 1] + x[i];
  }
  return out;
}

对于 RcppArmadillo：

#include <RcppArmadillo.h>
// [[Rcpp::depends(RcppArmadillo)]]

//' Matrix multiplication using Armadillo
//'
//' @param A A numeric matrix
//' @param B A numeric matrix
//' @return The matrix product A * B
//' @export
// [[Rcpp::export]]
arma::mat mat_mult(const arma::mat& A, const arma::mat& B) {
  return A * B;
}

预期结果： C++ 源文件存在于 src/my_function.cpp，具有有效的 // [[Rcpp::export]] 注解和 roxygen 风格的 //' 文档注释。

失败处理： 验证文件使用 #include <Rcpp.h>（或 Armadillo 使用 <RcppArmadillo.h>），导出注解位于函数签名正上方的单独行，且返回类型映射到有效的 Rcpp 类型。

第 3 步：生成 RcppExports

Rcpp::compileAttributes()
devtools::document()

预期结果： R/RcppExports.R 和 src/RcppExports.cpp 自动生成。

失败处理： 检查 C++ 语法错误。确保每个导出函数上方都有 // [[Rcpp::export]] 标签。

第 4 步：验证编译

devtools::load_all()

预期结果： 包编译并加载，无错误。

失败处理： 检查编译器输出中的错误。常见问题：

• 缺少系统头文件：安装开发库
• 语法错误：C++ 编译器消息指向具体行
• RcppArmadillo 缺少 Rcpp::depends 属性

第 5 步：编写编译代码的测试

test_that("cumsum_cpp matches base R", {
  x <- c(1, 2, 3, 4, 5)
  expect_equal(cumsum_cpp(x), cumsum(x))
})

test_that("cumsum_cpp handles edge cases", {
  expect_equal(cumsum_cpp(numeric(0)), numeric(0))
  expect_equal(cumsum_cpp(c(NA_real_, 1)), c(NA_real_, NA_real_))
})

预期结果： 测试通过，确认 C++ 函数产生与 R 等价物相同的结果，并正确处理边界情况（空向量、NA 值）。

失败处理： 如果 NA 处理测试失败，在 C++ 代码中使用 NumericVector::is_na() 添加显式 NA 检查。如果空输入测试失败，在函数顶部添加零长度向量的保护子句。

第 6 步：添加清理脚本

创建 src/Makevars：

PKG_CXXFLAGS = -O2

在包根目录创建 cleanup（用于 CRAN）：

#!/bin/sh
rm -f src/*.o src/*.so src/*.dll

设为可执行：chmod +x cleanup

预期结果： src/Makevars 设置编译器标志，cleanup 脚本删除编译对象。两个文件都存在于包根目录级别。

失败处理： 验证 cleanup 具有执行权限（chmod +x cleanup），且如果添加 Makefile 风格的规则，Makevars 使用制表符（而非空格）缩进。

第 7 步：更新 .Rbuildignore

确保编译产物被正确处理：

^src/.*\.o$
^src/.*\.so$
^src/.*\.dll$

预期结果： .Rbuildignore 模式阻止编译对象文件被包含在包 tarball 中，同时保留源文件和 Makevars。

失败处理： 运行 devtools::check() 并查找关于 src/ 中意外文件的 NOTE。调整 .Rbuildignore 模式以仅排除 .o、.so 和 .dll 文件。

验证清单

• devtools::load_all() 编译无警告
• 编译函数产生正确结果
• 边界情况测试通过（NA、空、大输入）
• R CMD check 通过，无编译警告
• RcppExports 文件已生成并提交
• 基准测试确认性能改进

常见问题

• 忘记 compileAttributes()：更改 C++ 文件后必须重新生成 RcppExports
• 整数溢出：对于大数值使用 double 而不是 int
• 内存管理：Rcpp 自动处理 Rcpp 类型的内存；不要手动 delete
• NA 处理：C++ 不了解 R 的 NA。使用 Rcpp::NumericVector::is_na() 检查
• 平台可移植性：避免平台特定的 C++ 特性。在 Windows、macOS 和 Linux 上测试
• 缺少 @useDynLib：包级文档必须包含 @useDynLib packagename, .registration = TRUE

相关技能

• create-r-package — 添加 Rcpp 之前的包设置
• write-testthat-tests — 测试编译函数
• setup-github-actions-ci — CI 必须有 C++ 工具链
• submit-to-cran — 编译包需要额外的 CRAN 检查