Getting Started • gdalraster.windows

library(gdalraster.windows)

What this package does

gdalraster.windows provides a reliable Windows workflow for using gdalraster against a modern, self-contained GDAL runtime built in CI — including features the default Rtools GDAL lacks (notably the GDAL Algorithm API with muparser, plus Arrow/Parquet, HDF5, NetCDF, and SpatiaLite drivers).

It does three things:

Installs a GDAL runtime bundle — a prebuilt, verified-closed set of DLLs, runtime data, and pure-python utilities published as a GitHub release asset.
Builds gdalraster from source against that bundle, into an isolated library so nothing you already have installed is touched.
Activates the runtime per session so the Windows loader, GDAL, and PROJ all resolve against the bundle.

Everything is non-destructive by default: the runtime lives under a package-managed user data directory, and the source-built gdalraster goes into its own library path rather than replacing a CRAN install.

Prerequisites

Two things must be on the machine before setup:

R on Windows — everything in this package is Windows-specific.
Rtools matching your R version — install_gdalraster() compiles gdalraster from source against the bundled GDAL headers. The prebuilt runtime bundle removes every other toolchain requirement (no MSYS2, no manual GDAL build), but the compile step itself needs Rtools. The function checks for a toolchain up front and aborts with guidance when none is found.

No other GDAL, Python, or spatial system dependencies are required: the runtime bundle is self-contained.

Quick start

One-time setup (using pak):

pak::pak("jimbrig/gdalraster.windows")

# download and install the GDAL runtime bundle (latest release asset)
gdalraster.windows::install_gdal_runtime()

# build gdalraster from source against that runtime
gdalraster.windows::install_gdalraster()

Then load and verify:

gdalraster.windows::load_gdalraster()

gdalraster::gdal_global_reg_names()
#> [1] "raster" "vector" "convert" "info" ... (non-empty)

A non-empty algorithm registry is the key success signal — on a broken toolchain/runtime combination it comes back as character(0).

Everyday use

After setup, attaching the package is enough. Its load hook automatically activates the installed runtime and prepends the isolated gdalraster library to .libPaths():

library(gdalraster.windows)
library(gdalraster)

gdalraster::gdal_global_reg_names()

If you prefer explicit control over the load order:

gdalraster.windows::load_gdal_dll()

library(gdalraster)
gdalraster::gdal_global_reg_names()

To make sessions bootstrap without attaching this package at all, install a managed .Rprofile hook (optional, and clearly delimited in the file):

gdalraster.windows::add_gdal_rprofile_hook()

Verifying the setup

verify_gdalraster_runtime() runs the full chain — activate runtime, load gdalraster, check the algorithm registry — and reports what it finds:

gdalraster.windows::verify_gdalraster_runtime()
#> v gdalraster is ready ("3.13.1")

Offline / air-gapped machines

install_gdal_runtime() downloads from GitHub Releases by default. Without network access, download the release asset from https://github.com/jimbrig/gdalraster.windows/releases on a connected machine, transfer it, and install directly:

gdalraster.windows::install_gdal_runtime(
  local_zip = "C:/Downloads/gdal-ucrt64-v3.13.1-windows-x64.zip"
)

Where things are installed

Component	Default location	Override
GDAL runtime	`tools::R_user_dir("gdalraster.windows", "data")`	`configure_gdal_home()`, `options(gdalraster.windows.gdal_home = ...)`, or the `GDALRASTER_WINDOWS_GDAL_HOME` environment variable
Source-built `gdalraster`	isolated `library/` folder under the same user data directory	`install_gdalraster(lib = ...)`

To install the source build into your regular user library instead — so plain library(gdalraster) resolves it without this package’s helpers — pass the library explicitly:

gdalraster.windows::install_gdalraster(lib = .libPaths()[1])

This replaces any existing gdalraster (e.g. the CRAN binary) in that library, and the bundled runtime must still be activated before the package loads in each session.

Next steps

The Runtime Guide covers session activation, configuration options, the startup hook, and embedded-python algorithms in depth.
Architecture explains why this package exists and how the runtime bundle is built.
Troubleshooting walks through the common failure modes and their fixes.