minirextendr — Scaffolding & Workflow Helper

minirextendr is a pure-R companion package that scaffolds, builds, and maintains R packages using the miniextendr Rust-R framework. Think of it as usethis for miniextendr projects.

Location: minirextendr/ in the monorepo.

🔗Installation

# From the monorepo:
just minirextendr-install

# Or directly:
R CMD INSTALL minirextendr

🔗Creating Projects

🔗Standalone R Package

library(minirextendr)
create_miniextendr_package("mypackage")

Creates a complete R package with Rust backend:

mypackage/
├── DESCRIPTION          # Config/build/bootstrap: TRUE
├── NAMESPACE
├── R/
├── configure.ac         # Autoconf source
├── configure            # Generated by autoconf
├── src/
│   ├── rust/
│   │   ├── Cargo.toml   # Rust dependencies
│   │   ├── lib.rs       # Your Rust code
│   │   ├── build.rs     # Build-time lint
│   ├── stub.c            # Minimal C stub for R linker
│   ├── Makevars.in
│   └── win.def.in
├── vendor/              # Vendored miniextendr crates
└── tools/               # config.guess, config.sub

🔗Monorepo (Workspace)

create_miniextendr_monorepo("myproject",
  package = "mypkg",
  crate_name = "mypkg-rs"
)

Creates a Cargo workspace with a separate Rust crate alongside the R package:

myproject/
├── Cargo.toml           # Workspace root
├── mypkg-rs/            # Main Rust crate
│   ├── Cargo.toml
│   └── src/lib.rs
├── mypkg/               # Generated R package
│   ├── src/rust/        # R-facing Rust bindings
│   └── vendor/
├── tools/               # Version management scripts
│   └── bump-version.R
└── justfile

To vendor from a specific GitHub tag instead of the default ("main"):

create_miniextendr_monorepo("myproject",
  miniextendr_version = "v0.1.0"
)

🔗Build Workflow

🔗Recommended: devtools (one-step)

devtools::document() handles the entire pipeline automatically:

devtools::document("mypackage")   # Compiles Rust + generates R wrappers + runs roxygen2
devtools::install("mypackage")    # Install the final package

How it works: devtools::document() calls pkgload::load_all(), which detects Config/build/bootstrap: TRUE in DESCRIPTION and runs bootstrap.R. That triggers ./configure → make → cargo build → document binary → R wrappers → roxygen2, all in a single invocation. No manual ./configure or two-pass install needed.

🔗Manual: step-by-step functions

For fine-grained control or when not using devtools:

miniextendr_autoconf(path = "mypackage")   # autoconf → generate configure
miniextendr_configure(path = "mypackage")  # ./configure → generate Makevars
miniextendr_build(path = "mypackage")      # R CMD INSTALL
miniextendr_document(path = "mypackage")   # devtools::document (regenerate wrappers)

🔗One-Shot Sync

miniextendr_sync() detects staleness and rebuilds only what’s needed:

miniextendr_sync(path = ".", mode = "if_stale", stage = "install")

Modes: "if_stale" (default), "always", "never". Stages: "install" (default), "wrappers", "build".

🔗Inline Rust Compilation

Compile Rust code on the fly without an existing package (like Rcpp’s sourceCpp()):

# Single function — auto-wraps with imports and module block
rust_function('
#[miniextendr]
pub fn add_one(x: i32) -> i32 { x + 1 }
')
add_one(41L)
#> [1] 42

# Vectors work too
rust_function('
#[miniextendr]
pub fn double_vec(x: Vec<f64>) -> Vec<f64> {
    x.into_iter().map(|v| v * 2.0).collect()
}
')
double_vec(c(1.0, 2.5, 3.0))
#> [1] 2.0 5.0 6.0

# Full source with multiple functions
rust_source(code = '
use miniextendr_api::miniextendr;

#[miniextendr]
pub fn greet(name: &str) -> String {
    format!("Hello, {}!", name)
}

#[miniextendr]
pub fn add(a: f64, b: f64) -> f64 { a + b }
// Registration is automatic via #[miniextendr].
')
greet("world")
#> [1] "Hello, world!"
add(1.5, 2.5)
#> [1] 4

🔗Caching

Results are MD5-cached: same code + features = instant reload. Calling the same rust_function() or rust_source() a second time skips compilation entirely.

# First call: compiles (~10-20s)
rust_function('#[miniextendr] pub fn sq(x: f64) -> f64 { x * x }')

# Second call: instant (cache hit)
rust_function('#[miniextendr] pub fn sq(x: f64) -> f64 { x * x }')

# Clear all cached compilations
rust_source_clean()

🔗Cargo Wrappers

Thin wrappers around cargo that target the package’s src/rust/ directory:

All accept path (default ".") and ... for extra arguments.

Note: cargo_fmt("--check") may report formatting diffs in vendored crates. This is expected — vendored code isn’t subject to local formatting rules.

🔗Feature Scaffolding

Add optional miniextendr features with proper Cargo.toml and R-side setup:

use_rayon()             # Parallel iteration
use_serde()             # Serde-based R ↔ Rust serialization
use_vctrs()             # vctrs integration
use_r6()                # R6 class system
use_s4()                # S4 class system
use_s7()                # S7 class system
use_feature_detection() # Conditional compilation via feature flags
use_vendor_lib()        # Vendor external Rust library for monorepo use

Each use_*() function:

1. Adds the Cargo feature to src/rust/Cargo.toml
2. Sets up any needed R-side dependencies (e.g., R6, S7 packages)
3. Updates miniextendr.yml configuration

🔗Feature Detection

use_feature_detection() sets up conditional compilation via R-detected feature flags:

# Initial setup — creates detect-features.R and wires it into configure.ac
use_feature_detection()

# After adding new features to miniextendr.yml, regenerate the detection script
update_feature_detection()

Features are detected at ./configure time and passed as --cfg flags to rustc.

🔗Vendoring

# Vendor miniextendr crates from local monorepo
vendor_miniextendr(local_path = "/path/to/miniextendr")

# Vendor miniextendr crates from GitHub release
vendor_miniextendr(version = "0.1.0")

# Vendor external crates from crates.io
vendor_crates_io(path = "mypackage")

# Check vendor freshness
vendor_sync(path = "mypackage")

# List available versions
miniextendr_available_versions()

🔗Diagnostics

has_miniextendr("mypackage")        # TRUE/FALSE — is this a miniextendr package?
miniextendr_status(path = ".")      # Show file status (present, stale, missing)
miniextendr_validate(path = ".")    # Validate project consistency
miniextendr_doctor(path = ".")      # Comprehensive health check
miniextendr_check_rust()            # Verify Rust toolchain is available

miniextendr_status() reports each build artifact’s state (present, stale, or missing). miniextendr_validate() checks structural consistency (DESCRIPTION fields, module declarations, etc.). miniextendr_doctor() runs the full suite including Rust toolchain checks.

Note: In monorepo mode, miniextendr_doctor() may report false-positive vendor warnings because vendored crates are resolved differently via [patch] in the workspace.

🔗Configuration

miniextendr.yml in the package root for project-level settings:

mx_config(path = ".")              # Read current config (returns named list)
mx_config_defaults()               # Show all defaults with descriptions

mx_config() merges project-level miniextendr.yml with built-in defaults. Settings include feature flags, class system choices, and build options. mx_config_defaults() lists every available setting with its default value.

🔗knitr / Rmarkdown / Quarto Integration

🔗Package Mode (in a package vignette)

# In a setup chunk:
miniextendr_knitr_setup()          # Syncs and registers {miniextendr} engine

Then use {miniextendr} chunks that evaluate as R code (the package is already built).

🔗Inline Mode (self-contained vignettes)

# In a setup chunk:
miniextendr_knitr_setup(path = NULL)

Each {miniextendr} chunk compiles Rust code via rust_source() and loads functions into the knitr environment. No existing package required.

🔗Render Helpers

Custom output formats that auto-sync before rendering:

# In YAML front matter:
output: minirextendr::miniextendr_html_document
output: minirextendr::miniextendr_pdf_document
output: minirextendr::miniextendr_word_document

For Quarto, use as a pre-render script:

# In _quarto.yml:
pre-render: Rscript -e "minirextendr::miniextendr_quarto_pre_render()"

🔗Upgrading Existing Packages

upgrade_miniextendr_package(path = "mypackage")

Updates templates, vendored crates, and configure.ac to match the latest minirextendr version.

🔗Caching

miniextendr_cache_info()     # Show cache location and size
miniextendr_clear_cache()    # Clear all caches

Cache location: rappdirs::user_cache_dir("minirextendr").

🔗Exported Functions Reference