Reference manual
Comprehensive guides to miniextendr runtime behavior, build tooling, macros, and subsystem details.
The reference side of the site is built for lookup speed as much as long-form reading.
How to use the manual
The manual is the exhaustive reference for miniextendr’s runtime, build system, derive macros, and platform-specific behavior.
Use it when you need the exact rules for a conversion, the details of an ALTREP implementation, or the packaging steps required for CRAN-compatible releases.
Full Index
Start near the top if you are learning the framework. Jump deeper when you already know the subsystem you need.
This guide walks you through creating your first R package with a Rust backend using miniextendr.
This document provides a high-level overview of miniextendr for evaluators, contributors, and users comparing approaches for Rust-R interop.
This guide documents how miniextendr converts between R and Rust types, including NA handling, coercion rules, and edge cases.
miniextendr supports five R class systems. This guide helps you choose the right one for your use case.
This page explains every package-like component in the repository: the core Rust crates, the excluded support tools, the R packages, and the fixture packages used to test cross-package behavior.
ALTREP (Alternative Representations) is R's system for creating custom vector implementations. miniextendr provides a powerful, safe abstraction for creating ALTREP vectors from Rust.
When you inspect rpkg/DESCRIPTION or a scaffolded package such as tests/model_project/DESCRIPTION, some lines are ordinary R-package metadata and some are there specifically to support the miniextendr build flow.
ExternalPtr<T> is a Box-like owned pointer that wraps R's EXTPTRSXP. It lets you hand ownership of Rust-allocated data to R and let R's garbage collector decide when to drop it.
This guide covers error handling patterns, panic safety, and best practices for robust R-Rust interop.
This document explains how to safely call R APIs from threads other than the main R thread.
How miniextendr packages its dependencies for CRAN offline builds.
miniextendr-api uses Cargo feature flags to enable optional integrations. Only default features are enabled automatically.
Complete reference for #[miniextendr] on every Rust item type.
This document explains how miniextendr automatically registers R-callable functions and initializes the runtime when an R package loads.
This guide explains how to expose Rust traits you don't own (from external crates) to R via miniextendr's trait ABI.
Practical recipes for exposing external Rust traits to R using the adapter pattern.
Zero-copy conversions between R vectors and Apache Arrow arrays.
Miniextendr provides seamless integration with Rayon for parallel computation in R packages. This enables writing high-performance parallel code while maintaining R's safety guarantees.
This document explains the thread safety invariants and FFI safety requirements for miniextendr. Read this before contributing unsafe code or modifying the worker, thread, or unwind_protect modules.
This document covers miniextendr's RAII-based GC protection facilities.
How miniextendr catches panics at Rust-R boundaries and provides structured diagnostics.
This document describes the Coerce<R> trait system for converting Rust types to R's native scalar types.
This document describes how to implement R's as.<class>() coercion generics for Rust types using the #[miniextendr(as = "...")] attribute.
This document describes how miniextendr converts between R types and Rust types. Conversions are governed by three modes (normal, coerce, strict) and apply to both directions: R-to-Rust (TryFromSexp) and Rust-to-R (IntoR).
miniextendr provides comprehensive support for converting between Rust types and R data frames, with three complementary approaches offering different trade-offs between ergonomics and flexibility.
R connections are the standard abstraction for I/O in R -- readLines(), writeLines(), readBin(), writeBin(), scan(), and many other functions all operate on connections. miniextendr lets you create custom R connections backed by Rust types, enabling you to expose any Rust I/O source or sink to R's connection infrastructure.
Safe wrappers for building and evaluating R function calls from Rust.
How to map Rust enums to R factors and character strings.
This document describes miniextendr's support for R's ... (dots) arguments and the typed_list! macro for structured validation.
How to implement S3 generics (print, format, etc.) with #[miniextendr(s3)].
Real-world examples of ALTREP usage patterns in miniextendr.
One-page reference for miniextendr's ALTREP system.
Controls how panics and R errors are caught in ALTREP callback trampolines.
How miniextendr handles ALTREP vectors when R passes them to Rust functions.
Sparse iterator ALTREP vectors use Iterator::nth() to skip directly to requested indices, caching only the elements that are actually accessed. This makes them ideal for large vectors where only a few elements are needed.
Compile-time dimensioned wrappers for R arrays, matrices, and vectors.
Convert Rust POD (Plain Old Data) types to and from R raw vectors using bytemuck.
The serde_r feature provides direct serialization between Rust types and native R objects without going through an intermediate format like JSON. This enables efficient, type-preserving conversions that respect R's native data structures.
miniextendr provides the #[derive(Vctrs)] macro to create vctrs-compatible S3 vector classes from Rust structs. These types integrate seamlessly with the tidyverse ecosystem.
Safe access to R's random number generators from Rust.
This document covers miniextendr's UTF-8 locale requirement and encoding probing utilities.
miniextendr integrates with the lifecycle R package to mark functions as experimental, deprecated, or defunct. The proc macro generates lifecycle badges, runtime warnings, and roxygen tags automatically.
Strict mode rejects lossy type conversions that would silently widen or truncate values. When enabled, out-of-range values panic instead of being coerced.
Project-wide defaults for #[miniextendr] options, controlled via Cargo features.
This document tracks usage of non-API R functions in miniextendr. Non-API functions are detected by R CMD check via tools:::.checksosymbols.
This guide explains how to extend miniextendr with custom types, enabling them to be passed between Rust and R.
The trait ABI lets R (and other packages) call Rust trait methods without knowing the concrete Rust type at compile time. It does this by storing a tiny "header + vtable" next to the object and using R external pointers to carry it around.
This document describes the trait ABI system for cross-package trait dispatch.
This document explains how miniextendr links against R's shared library (libR) for both R packages and standalone Rust binaries.
How R builds packages with compiled code, and how miniextendr integrates with it.
The minirextendr package provides scaffolding templates for creating new R packages with Rust backends. This document explains how the template system works and how to keep templates in sync with the reference implementation.
This file documents the rationale for the recent refactor that moved R linking and embedded-R initialization into miniextendr-engine, and made the benchmark crate (miniextendr-bench) depend on it.
This document explains how to use C headers from installed R packages in a miniextendr Rust crate. The technique uses bindgen to generate Rust FFI bindings at development time, and R's standard build system to compile the required C shim files.
Open the MSYS2 UCRT64 shell that ships with Rtools45. On a default install this is:
This document covers RAllocator, a Rust GlobalAlloc implementation backed by R's memory manager.
R strings (CHARSXPs), symbols, and class vectors are immutable once created. When the same value is needed repeatedly — especially on hot paths like vectorized conversions — cache it once and reuse the pointer.
How to control which R representation a Rust type uses when returned from #[miniextendr] functions.
The #[miniextendr] macro automatically adds #[track_caller] to Rust functions for better panic location reporting.
This guide covers common error messages from #[miniextendr] proc macros and the miniextendr-lint static analysis tool.
miniextendr provides an adapter that routes indicatif progress bar output through R's console, so progress bars render correctly in R terminals, RStudio, and other R frontends.
All environment variables that affect miniextendr's build, configure, test, and lint processes.
Quick reference for common development tasks. See CLAUDE.md for complete build system documentation.
This document covers maintenance tasks for the miniextendr project.
Baseline measurements for miniextendr's runtime overhead on Apple M3 Max (macOS, Rust 1.93, R 4.5). Run date: 2026-02-18.
Common issues and solutions when developing with miniextendr.
This document describes the smoke test process for the miniextendr project. It covers the full "demanding" smoke lane -- the most thorough validation pass, intended for release gates and nightly CI runs.
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.
We explored extracting miniextendr-api's optional features (ndarray, nalgebra, serde, rayon, etc.) into separate miniextendr-<name> crates. The goal was to reduce miniextendr-api's surface area and let users depend only on what they need.
This document catalogs known gaps, limitations, and undocumented behaviors in miniextendr. It serves as both user documentation and a roadmap for future improvements.
This document lists practical feature candidates for upcoming maintenance cycles. Items are scoped to be incremental and compatible with the current architecture.