---

name: add-rcpp-integration locale: wenyan source_locale: en source_commit: 82c77053 fence_basis_commit: 82c77053 translator: "Julius Brussee homage — caveman" translation_date: "2026-04-19" description: > Add Rcpp or RcppArmadillo integration to an R package for high-performance C++ code. Covers setup, writing C++ functions, RcppExports generation, testing compiled code, and debugging. Use when an R function is too slow and profiling confirms a bottleneck, when you need to interface with existing C/C++ libraries, or when implementing algorithms (loops, recursion, linear algebra) that benefit from compiled code. license: MIT allowed-tools: Read Write Edit Bash Grep Glob metadata: author: Philipp Thoss version: "1.0" domain: r-packages complexity: advanced language: R tags: r, rcpp, cpp, performance, compiled-code

納 Rcpp 整合

於 R 包以 Rcpp 納 C++ 碼，用於性能要之操作。

用時

• R 函過緩而剖析確認瓶頸乃用
• 需連既有 C/C++ 庫乃用
• 實益於編譯之算法（環、遞歸）乃用
• 增 RcppArmadillo 以行線性代數乃用

入

• 必要：既存之 R 包
• 必要：將以 C++ 代或增之 R 函
• 可選：將連之外 C++ 庫
• 可選：用 RcppArmadillo 乎（默：純 Rcpp）

法

第一步：設 Rcpp 基

usethis::use_rcpp()

此舉：

• 建 src/ 目
• 於 DESCRIPTION 之 LinkingTo 與 Imports 添 Rcpp
• 建 R/packagename-package.R，含 @useDynLib 與 @importFrom Rcpp sourceCpp
• 更 .gitignore 以避編譯檔

用 RcppArmadillo：

usethis::use_rcpp_armadillo()

得： src/ 目已建，DESCRIPTION 已更 LinkingTo 與 Imports 之 Rcpp，R/packagename-package.R 含 @useDynLib 指令。

敗則： 若 usethis::use_rcpp() 敗，手建 src/，於 DESCRIPTION 添 LinkingTo: Rcpp 與 Imports: Rcpp，於包級文檔添 #' @useDynLib packagename, .registration = TRUE 與 #' @importFrom Rcpp sourceCpp。

第二步：書 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 型。

第三步：生 RcppExports

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

得： R/RcppExports.R 與 src/RcppExports.cpp 自生。

敗則： 察 C++ 之語法訛。確 // [[Rcpp::export]] 置各導出函之上。

第四步：驗編譯

devtools::load_all()

得： 包編而載無訛。

敗則： 察編譯器之出。常患：

• 系統頭缺：裝開發庫
• 語法訛：編譯器指其行
• RcppArmadillo 缺 Rcpp::depends 注

第五步：書編碼之試

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() 明察。空入試敗則函首加長零之守。

第六步：添清理之本

建 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），Makevars 用 tab（非空格）縮以寫 Makefile 之則。

第七步：更 .Rbuildignore

確編譯物已處：

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

得： .Rbuildignore 之式避編譯物入包焰，而存源與 Makevars。

敗則： 行 devtools::check() 察 src/ 未期之檔之 NOTE。調 .Rbuildignore 只排 .o、.so、.dll。

驗

• devtools::load_all() 編而無警
• 編函生正果
• 邊例（NA、空、大入）之試皆過
• R CMD check 過無編譯之警
• RcppExports 檔已生並提交
• 以基準確性能之進

陷

• 遺 compileAttributes()：改 C++ 後必再生 RcppExports
• 整溢：大數用 double 非 int
• 記憶之治：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 之查