Skip to contents

Using gdalraster.windows on Windows

Source: vignettes/runtime-guide.Rmd
runtime-guide.Rmd

What this package does

gdalraster.windows helps you use gdalraster with a bundled GDAL runtime on Windows.

Typical flow:

  1. install runtime bundle
  2. build gdalraster from source against that runtime
  3. load and verify in your R session

Quick start 

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

gdalraster.windows::install_gdal_runtime()
gdalraster.windows::install_gdalraster()

library(gdalraster.windows)
gdalraster::gdal_global_reg_names()

If runtime and custom gdalraster are already installed:

Explicit load flow:

gdalraster.windows::load_gdal_dll()
gdalraster.windows::load_gdalraster()
gdalraster::gdal_global_reg_names()

Offline / air-gapped install

Download the release asset from https://github.com/jimbrig/gdalraster.windows/releases on a connected machine, transfer it, then:

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

Embedded-python algorithms

Some GDAL algorithms (e.g. gdal driver gpkg validate) are implemented in Python: libgdal embeds a CPython interpreter at runtime and imports the pure-python osgeo_utils package. The runtime bundle ships that package under <gdal_home>/python, and activate_gdal_runtime() exposes it to the embedded interpreter by prepending it to PYTHONPATH (session-scoped).

library(gdalraster.windows)
library(gdalraster)

alg <- gdalraster::gdal_alg(cmd = "driver gpkg validate")
alg$setArg("dataset", "path/to/file.gpkg")
alg$setArg("full-check", TRUE)
alg$run()
alg$output()
#> [1] "Checking gpkg_spatial_ref_sys\n...\nValidation succeeded"

A python.exe must be discoverable on PATH for GDAL to embed an interpreter (Rtools’ UCRT64 python works, as does any system python). If such an algorithm fails with ModuleNotFoundError: No module named 'osgeo_utils', the runtime bundle predates python support — reinstall with install_gdal_runtime(overwrite = TRUE) and re-activate.

Default install behavior

By default:

  • runtime installs under package-managed user directories
  • source-built gdalraster installs to an isolated library path

Persistent startup behavior is optional:

gdalraster.windows::add_gdal_rprofile_hook()

Troubleshooting basics

In a fresh session:

  1. gdalraster.windows::activate_gdal_runtime()
  2. library(gdalraster)
  3. length(gdalraster::gdal_global_reg_names()) > 0

If this fails, see dev/docs/05-troubleshooting.md.

Background reading