整合 Rcpp

藉 Rcpp 將 C++ 碼整合入 R 套件，以應對效能關鍵之操作。

適用時機

• 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()

預期： 套件編譯並載入而無誤。

失敗時： 查編譯器輸出之錯誤。常見問題：

• 缺系統標頭：安裝開發函式庫
• 語法錯誤：C++ 編譯訊息會指出該行
• 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()

加入明確之 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

），且若加入 Makefile 風規則，

Makevars

之縮排用 tab 而非空格。

步驟七：更新 .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 檢查