What rvtk does
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:
- A universally installed VTK. Headers and libraries are found in a system VTK installation when one exists, and are otherwise downloaded at install time as pre-built static libraries — so your users do not need to install VTK themselves.
-
Compiler flags —
rvtk::CppFlags()returns the-I(include) paths. -
Linker flags —
rvtk::LdFlags()(and its response-file variantrvtk::LdFlagsFile()) returns the-L/-larguments. -
Automated setup —
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.
How rvtk finds VTK
rvtk’s own configure script runs at install time and writes the result to inst/vtk.conf. The strategies differ by platform.
macOS and Linux
- The environment variable
VTK_DIR(path to a VTK build/install tree). -
Homebrew (
brew --prefix vtk) — macOS only. -
pkg-config(vtk-9.7,vtk-9.6,vtk-9.5, …,vtk-9.1). - Well-known system prefixes (
/usr,/usr/local) — Linux only. - Download pre-built static libraries from https://github.com/astamm/rvtk/releases as a fallback.
Windows
configure.win tries, in order:
- The environment variable
VTK_DIR. - Rtools45
pacman(queries installed packages; never installs automatically). - Common Rtools45 / MSYS2 prefixes (
/x86_64-w64-mingw32.static.posix,/ucrt64,/mingw64, …). - Download pre-built libraries (static
.aby default, or shared DLLs whenVTK_LINK_TYPE=sharedis 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.
Compatibility matrix
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.
Bundled VTK modules
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.7.2"
CppFlags()
#> -isystem/home/runner/work/_temp/Library/rvtk/prebuilt/include/vtk-9.7The 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.
The two setup strategies
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).
Strategy A — 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:
- Adds
rvtkto theImportsfield ofDESCRIPTION. - Writes
src/Makevars(macOS/Linux build rules). - Writes
src/Makevars.win(Windows build rules). - Writes
tools/configure.R, a small R helper that resolves the flags at install time. - Adds
src/vtk_libs.rspto.gitignore(the response file is generated at install time and must not be committed). - Creates
R/rvtk_imports.Rwith a minimal@importFrom rvtkroxygen tag so thatR CMD checkdoes not warn about an unusedImportsentry.
If some of these files already exist, use_rvtk() asks before overwriting in an interactive session and skips them silently otherwise.
Strategy B — manual setup
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
NULLHow the build-time resolution works
There 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.
Choosing the VTK modules to link against
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:
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"))
#> -Wl,--start-group /home/runner/work/_temp/Library/rvtk/prebuilt/lib/libvtkcgns-9.7.a /home/runner/work/_temp/Library/rvtk/prebuilt/lib/libvtkCommonCore-9.7.a /home/runner/work/_temp/Library/rvtk/prebuilt/lib/libvtkCommonDataModel-9.7.a /home/runner/work/_temp/Library/rvtk/prebuilt/lib/libvtkexodusII-9.7.a /home/runner/work/_temp/Library/rvtk/prebuilt/lib/libvtkexpat-9.7.a /home/runner/work/_temp/Library/rvtk/prebuilt/lib/libvtkfmt-9.7.a /home/runner/work/_temp/Library/rvtk/prebuilt/lib/libvtkfreetype-9.7.a /home/runner/work/_temp/Library/rvtk/prebuilt/lib/libvtkgl2ps-9.7.a /home/runner/work/_temp/Library/rvtk/prebuilt/lib/libvtkglad-9.7.a /home/runner/work/_temp/Library/rvtk/prebuilt/lib/libvtkhdf5_hl-9.7.a /home/runner/work/_temp/Library/rvtk/prebuilt/lib/libvtkhdf5-9.7.a /home/runner/work/_temp/Library/rvtk/prebuilt/lib/libvtkIOLegacy-9.7.a /home/runner/work/_temp/Library/rvtk/prebuilt/lib/libvtkioss-9.7.a /home/runner/work/_temp/Library/rvtk/prebuilt/lib/libvtkjpeg-9.7.a /home/runner/work/_temp/Library/rvtk/prebuilt/lib/libvtkjsoncpp-9.7.a /home/runner/work/_temp/Library/rvtk/prebuilt/lib/libvtkkissfft-9.7.a /home/runner/work/_temp/Library/rvtk/prebuilt/lib/libvtklibharu-9.7.a /home/runner/work/_temp/Library/rvtk/prebuilt/lib/libvtklibproj-9.7.a /home/runner/work/_temp/Library/rvtk/prebuilt/lib/libvtklibxml2-9.7.a /home/runner/work/_temp/Library/rvtk/prebuilt/lib/libvtkloguru-9.7.a /home/runner/work/_temp/Library/rvtk/prebuilt/lib/libvtklz4-9.7.a /home/runner/work/_temp/Library/rvtk/prebuilt/lib/libvtklzma-9.7.a /home/runner/work/_temp/Library/rvtk/prebuilt/lib/libvtkmetaio-9.7.a /home/runner/work/_temp/Library/rvtk/prebuilt/lib/libvtknetcdf-9.7.a /home/runner/work/_temp/Library/rvtk/prebuilt/lib/libvtkogg-9.7.a /home/runner/work/_temp/Library/rvtk/prebuilt/lib/libvtkpng-9.7.a /home/runner/work/_temp/Library/rvtk/prebuilt/lib/libvtkpugixml-9.7.a /home/runner/work/_temp/Library/rvtk/prebuilt/lib/libvtkscn-9.7.a /home/runner/work/_temp/Library/rvtk/prebuilt/lib/libvtksqlite-9.7.a /home/runner/work/_temp/Library/rvtk/prebuilt/lib/libvtksys-9.7.a /home/runner/work/_temp/Library/rvtk/prebuilt/lib/libvtktheora-9.7.a /home/runner/work/_temp/Library/rvtk/prebuilt/lib/libvtktiff-9.7.a /home/runner/work/_temp/Library/rvtk/prebuilt/lib/libvtktoken-9.7.a /home/runner/work/_temp/Library/rvtk/prebuilt/lib/libvtkverdict-9.7.a /home/runner/work/_temp/Library/rvtk/prebuilt/lib/libvtkx11-9.7.a /home/runner/work/_temp/Library/rvtk/prebuilt/lib/libvtkzlib-9.7.a -Wl,--end-groupWriting the C++ that uses VTK
A 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.
Shared VTK on Windows
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:
-
Version sync matters. Your package is compiled against the specific VTK version shipped with the rvtk installed at compile time. If rvtk is updated to a new VTK version, your package must be recompiled against the new rvtk to match the new DLL names (e.g.
vtkCommonCore-9.8.dll). - DLL footprint lives in rvtk only. Downstream packages do not receive a copy of the DLLs; they rely on rvtk’s staged directory at run time.
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.
Verifying that linking worked
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.
Summary
- rvtk locates VTK at install time and exposes the resulting flags through
CppFlags(),LdFlags(),LdFlagsFile(), andVtkVersion(). -
use_rvtk()writes every build-time file for a downstream package; the same files can be written manually, byte-for-byte identically. - Use the
modulesargument to link only what you need — especially with the macOS static bundle. - Prefer
LdFlagsFile()on Windows to avoid the command-line length limit. - For CRAN, prefer the static pre-built build; for Windows shared builds, keep rvtk and the downstream package in lockstep.
