library(rvtk)library(rvtk)rvtk is an infrastructure package: it does not itself build VTK meshes or render scenes. Instead, it makes the Visualization Toolkit (VTK) available to other R packages that need to link against it from C++. If you are writing an R package with native code that #includes VTK headers and calls VTK classes, rvtk gives you four things:
rvtk::CppFlags() returns the -I (include) paths.rvtk::LdFlags() (and its response-file variant rvtk::LdFlagsFile()) returns the -L/-l arguments.rvtk::use_rvtk() writes all the build-time glue files for you.This vignette explains how VTK is located on each platform, what files a downstream package needs, how the two setup strategies (use_rvtk() versus hand-written files) relate, and how to verify that linking actually worked.
rvtk’s own configure script runs at install time and writes the result to inst/vtk.conf. The strategies differ by platform.
VTK_DIR (path to a VTK build/install tree).brew --prefix vtk) — macOS only.pkg-config (vtk-9.7, vtk-9.6, vtk-9.5, …, vtk-9.1)./usr, /usr/local) — Linux only.configure.win tries, in order:
VTK_DIR.pacman (queries installed packages; never installs automatically)./x86_64-w64-mingw32.static.posix, /ucrt64, /mingw64, …)..a by default, or shared DLLs when VTK_LINK_TYPE=shared is set before installation).Static .a libraries are preferred over shared .dll.a import libraries at the same prefix; if only shared libraries are available, rvtk accepts them and stages the VTK DLLs itself so downstream packages need no extra configuration.
The pre-built fallback is available for the following platform × strategy combinations; a system VTK installation (≥ 9.1.0) found via VTK_DIR, pkg-config, Homebrew, or pacman is always preferred when present.
| Platform | Pre-built fallback | Notes |
|---|---|---|
| macOS arm64 | static .a |
|
| macOS x86_64 | static .a |
|
| Linux x86_64 (glibc) | static .a |
|
| Linux x86_64 (musl / Alpine) | static .a |
headless build: VTK_USE_X=OFF, RenderingOpenGL2=NO |
| Linux aarch64 | static .a |
|
| Windows x64 | static .a (default) or shared DLLs (VTK_LINK_TYPE=shared) |
On Windows the modules VTK_IONetCDF, VTK_IOHDF, and VTK_GeovisCore are disabled because netcdf and libproj are not available in the Rtools45 static.posix sysroot; downstream packages requiring them cannot be built on Windows with rvtk’s pre-built libraries.
The pre-built bundles are built with VTK_BUILD_ALL_MODULES=OFF and the following modules explicitly enabled (VTK resolves and includes all transitive dependencies automatically):
| Module | Purpose |
|---|---|
VTK_IOLegacy |
Legacy VTK file format reader/writer (.vtk) |
VTK_IOXML |
XML-based VTK file formats (.vtp, .vtu, .vts, …) |
VTK_IOCore |
Core I/O infrastructure shared by all I/O modules |
VTK_IOGeometry |
Readers/writers for common geometric formats (.ply, .stl, …) |
VTK_FiltersCore |
Core algorithmic filters (threshold, transform points, …) |
VTK_FiltersGeneral |
General-purpose filters (append, clip, decimate, …) |
VTK_FiltersGeometry |
Filters that modify or convert dataset geometry |
VTK_FiltersModeling |
Filters for geometric modeling and meshing |
VTK_FiltersExtraction |
Filters that extract subsets of data |
VTK_CommonCore |
Core data structures, object model, logging |
VTK_CommonDataModel |
Datasets, cells, point/cell data arrays |
Typical transitive dependencies pulled in automatically include VTK_CommonExecutionModel, VTK_CommonMath, VTK_CommonMisc, VTK_CommonSystem, VTK_CommonTransforms, VTK_IOXMLParser, and vtksys.
Once rvtk is installed, CppFlags(), LdFlags(), LdFlagsFile(), and VtkVersion() read vtk.conf and report whatever VTK was found:
VtkVersion()
#> [1] "9.5.0"
CppFlags()
#> -isystem/opt/homebrew/opt/vtk/include/vtk-9.5The exact flags depend on the detected VTK strategy: system shared libraries on macOS/Linux, .a archives in the pre-built tree, .dll.a import libraries + DLLs on Windows, etc. Your downstream package never has to figure this out itself — it simply calls back into rvtk.
There are two equivalent ways to configure a downstream package. They produce byte-identical files (this equivalence is asserted in rvtk’s own CI on every platform and VTK strategy).
use_rvtk()The recommended one-call approach, in the spirit of usethis:
# from the root of your package (e.g. yourpackage/)
rvtk::use_rvtk()This does the following, in order:
rvtk to the Imports field of DESCRIPTION.src/Makevars (macOS/Linux build rules).src/Makevars.win (Windows build rules).tools/configure.R, a small R helper that resolves the flags at install time.src/vtk_libs.rsp to .gitignore (the response file is generated at install time and must not be committed).R/rvtk_imports.R with a minimal @importFrom rvtk roxygen tag so that R CMD check does not warn about an unused Imports entry.If some of these files already exist, use_rvtk() asks before overwriting in an interactive session and skips them silently otherwise.
Everything use_rvtk() writes can also be written by hand, exactly as documented below (the README’s “Manual setup” section also walks through it). The files are:
DESCRIPTION — declare the dependency:
Imports: rvtk
src/Makevars:
PKG_CPPFLAGS = `"$(R_HOME)/bin/Rscript" ../tools/configure.R --cppflags`
PKG_LIBS = `"$(R_HOME)/bin/Rscript" ../tools/configure.R --libs`src/Makevars.win:
PKG_CPPFLAGS = $(shell "$(R_HOME)/bin$(R_ARCH_BIN)/Rscript" ../tools/configure.R --cppflags)
PKG_LIBS = $(shell "$(R_HOME)/bin$(R_ARCH_BIN)/Rscript" ../tools/configure.R --libs)tools/configure.R:
args <- commandArgs(trailingOnly = TRUE)
flag <- if (length(args)) args[1L] else "--cppflags"
vtk_modules <- c(
"vtkIOLegacy",
"vtkIOXML",
"vtkIOXMLParser",
"vtkIOCore",
"vtkIOGeometry",
"vtkFiltersCore",
"vtkFiltersGeneral",
"vtkFiltersGeometry",
"vtkFiltersModeling",
"vtkFiltersExtraction",
"vtkCommonCore",
"vtkCommonDataModel",
"vtkCommonExecutionModel",
"vtkCommonMath",
"vtkCommonMisc",
"vtkCommonSystem",
"vtkCommonTransforms",
"vtksys"
)
if (flag == "--cppflags") {
rvtk::CppFlags()
} else if (flag == "--libs") {
rvtk::LdFlagsFile(path = "vtk_libs.rsp", modules = vtk_modules)
}.gitignore — add src/vtk_libs.rsp.
R/rvtk_imports.R — import at least one rvtk function so that R CMD check sees the Imports entry as used:
#' @importFrom rvtk CppFlags LdFlagsFile
NULLThere is no shell configure script in the downstream package. Instead, the Makevars files shell out to Rscript at compile time:
"$(R_HOME)/bin/Rscript" ../tools/configure.R --cppflagstools/configure.R is the only file that knows about rvtk’s functions; it prints the flags to standard output, and Make captures them into PKG_CPPFLAGS / PKG_LIBS. This redirection through Rscript is exactly how the flags stay correct no matter where VTK was found — the R session doing the compilation has the same library paths as the rvtk installation being linked against.
On Windows the Make syntax is different ($(shell "$(R_HOME)/bin$(R_ARCH_BIN)/Rscript" …)) because GNU make on Windows needs the $(shell …) form and the R_ARCH_BIN subdirectory.
The --libs path calls LdFlagsFile(), not LdFlags(), because the full set of VTK -l flags can exceed the 8 191-character Windows command-line limit. On Windows the flags are written to src/vtk_libs.rsp and PKG_LIBS receives the short token @vtk_libs.rsp. On macOS and Linux the raw flags are returned directly.
The pre-built bundles shipped with rvtk contain far more than the modules you are likely to use (I/O, filtering, and core modules plus their transitive dependencies). By default use_rvtk() links the following set:
c(
"vtkIOLegacy",
"vtkIOXML",
"vtkIOXMLParser",
"vtkIOCore",
"vtkIOGeometry",
"vtkFiltersCore",
"vtkFiltersGeneral",
"vtkFiltersGeometry",
"vtkFiltersModeling",
"vtkFiltersExtraction",
"vtkCommonCore",
"vtkCommonDataModel",
"vtkCommonExecutionModel",
"vtkCommonMath",
"vtkCommonMisc",
"vtkCommonSystem",
"vtkCommonTransforms",
"vtksys"
)
#> [1] "vtkIOLegacy" "vtkIOXML"
#> [3] "vtkIOXMLParser" "vtkIOCore"
#> [5] "vtkIOGeometry" "vtkFiltersCore"
#> [7] "vtkFiltersGeneral" "vtkFiltersGeometry"
#> [9] "vtkFiltersModeling" "vtkFiltersExtraction"
#> [11] "vtkCommonCore" "vtkCommonDataModel"
#> [13] "vtkCommonExecutionModel" "vtkCommonMath"
#> [15] "vtkCommonMisc" "vtkCommonSystem"
#> [17] "vtkCommonTransforms" "vtksys"Restricting linking to only the modules you need is strongly recommended when you use the pre-built static bundle on macOS. The bundle is built as a collection of static archives, and the linker (with R’s default -undefined dynamic_lookup) resolves symbols lazily at load time rather than at build time. If a kept library contains an object file that references a symbol from a module that is not in your requested set, that object can be dragged in and the missing symbol shows up only when the package is loaded:
symbol not found in flat namespace '__ZN17vtkCellGridReader3NewEv'
For example, the pre-built libraries contain modules (such as I/O readers) that are not part of the default module list; linking too broadly can pull in an object referencing one of them. Because the pre-built libraries are static archives on macOS/Linux, the fixed module list in tools/configure.R is what prevents this. Pass only the modules your code actually uses:
rvtk::use_rvtk(
modules = c(
"vtkIOLegacy",
"vtkCommonCore",
"vtkCommonDataModel"
)
)This also keeps link time down and reduces the size of your compiled code. With a system shared VTK installation, the loader resolves symbols at run time and the full modules = NULL set is fine.
If you set up files manually, edit the vtk_modules vector in tools/configure.R the same way.
The modules argument is also accepted directly by LdFlags() and LdFlagsFile() if you need finer control in your own build scripts:
# flags for just the I/O + core modules
LdFlags(modules = c("vtkIOLegacy", "vtkCommonCore", "vtkCommonDataModel"))
#> -L/opt/homebrew/opt/vtk/lib -lvtkIOLegacy-9.5 -lvtkIOXML-9.5 -lvtkIOXMLParser-9.5 -lvtkIOCore-9.5 -lvtkIOGeometry-9.5 -lvtkFiltersCore-9.5 -lvtkFiltersGeneral-9.5 -lvtkFiltersGeometry-9.5 -lvtkFiltersModeling-9.5 -lvtkFiltersExtraction-9.5 -lvtkCommonCore-9.5 -lvtkCommonDataModel-9.5 -lvtkCommonExecutionModel-9.5 -lvtkCommonMath-9.5 -lvtkCommonMisc-9.5 -lvtkCommonSystem-9.5 -lvtkCommonTransforms-9.5 -lvtksys-9.5A minimal src/code.cpp that exercises the link looks like this:
// src/code.cpp
#include <cpp11.hpp>
#include <vtkNew.h>
#include <vtkPolyData.h>
[[cpp11::register]]
int vtk_poly_data_npoints() {
vtkNew<vtkPolyData> pd;
return static_cast<int>(pd->GetNumberOfPoints());
}Include the headers exactly as the VTK include directory is laid out in the detected installation (e.g. vtk-9.7). -isystem (from CppFlags() on macOS/Linux) makes these includes searchable without turning their content into warnings.
If you use cpp11 (as in rvtk’s own downstream CI), run cpp11::cpp_register() after adding your functions. Note: cpp_register() copies only the function name, return type, and arguments into R/cpp11.R — roxygen tags such as #' @export must live in a separate R file for the wrapper function you export, or the function will not appear in NAMESPACE.
If rvtk is installed with VTK_LINK_TYPE=shared (or a system installation provides only shared libraries), downstream packages link against .dll.a import libraries and load the VTK DLLs at run time from rvtk’s inst/vtk-dlls/ (prepended to PATH by rvtk’s .onLoad hook). Two consequences for package authors:
vtkCommonCore-9.8.dll).For CRAN submissions the static pre-built build is recommended: it is self-contained inside your package binary and has no run-time coupling to rvtk’s DLLs.
Before submitting your package, run a full R CMD check; then load the installed package in a fresh session and call the C++ entry point:
# in a fresh R session, after R CMD INSTALL
library(yourpackage)
yourpackage::vtk_poly_data_npoints() # expect 0: a brand-new vtkPolyData has no pointsIf the package builds but fails to load with an undefined-symbol error, the usual cause is a module being referenced by the code but missing from the modules vector, or a symbol being dragged in from a module outside the requested set (e.g. vtkCellGridReader when vtkIOCellGrid is not listed). Narrow the module list to exactly what the code uses and rebuild.
CppFlags(), LdFlags(), LdFlagsFile(), and VtkVersion().use_rvtk() writes every build-time file for a downstream package; the same files can be written manually, byte-for-byte identically.modules argument to link only what you need — especially with the macOS static bundle.LdFlagsFile() on Windows to avoid the command-line length limit.