Skip to contents

Architecture

Source: vignettes/architecture.qmd

Why this package exists

gdalraster binds to GDAL’s C++ API. On Windows, gdalraster.dll and libgdal-*.dll therefore must be built in a compatible MinGW/UCRT ABI environment. The default Rtools GDAL has also historically lacked the Algorithm API registration and driver profile this project needs.

The repository builds a modern shared GDAL in MSYS2 UCRT64, publishes a verified runtime bundle, and compiles gdalraster from source against that bundle.

Install-time vendoring

Version 0.4.0 moves all runtime selection to install time:

bundle SDK -> source build -> staged gdalraster package
                                |
                                +-- libs/x64: native dependency closure
                                +-- gdal + proj: matching data
                                +-- python: osgeo_utils
                                +-- build provenance

The staged package replaces the destination only after compilation and vendoring succeed. This prevents a failed build or locked destination from leaving a partially updated package.

Fresh-session loading

R’s Windows loader calls library.dynam() with the installed package’s libs/x64 directory. That directory becomes the search location for the entire load-time dependency graph, so the vendored libgdal and dependency DLLs resolve next to gdalraster.dll.

GDAL and PROJ data are package-internal, matching the GDAL version used at compile time. No startup hook, DLL preload, PATH mutation, or GDAL/PROJ environment export is part of the package architecture.

Multi-GDAL machines

Another GDAL on PATH does not override the vendored DLL while gdalraster.dll is loading. The remaining process-level exception is an identically named GDAL DLL already loaded before gdalraster; Windows module resolution can reuse an existing loaded module by name. gdal_sitrep() reports an already-loaded libgdal module.

Command-line GDAL installations from pixi, conda, OSGeo4W, or MSYS2 remain independent. Their executables can coexist with the vendored R package.

Bundle responsibilities

The build workflow and scripts are authoritative for the distributable GDAL SDK:

  • .github/workflows/build.yml;
  • tools/build_gdal.sh; and
  • tools/collect_dlls.sh.

They build GDAL, collect the non-Windows dependency closure, validate bundle layout and loadability, and publish release assets. The package does not reimplement those tasks.

The Arrow/Parquet TLS correction belongs to this bundle layer. The package contains no session-order or Parquet initialization workaround. Package CI instead verifies a first Parquet open in a fresh process so bundle regressions are observable.

Package responsibilities

The R package:

  1. installs and stamps the SDK;
  2. compiles gdalraster with scoped Makevars and environment state;
  3. vendors DLLs, data, and Python utilities;
  4. provisions the managed Python .pth; and
  5. verifies the result in fresh processes.

The end-to-end workflow consumes these exported functions exactly as users do.

Provenance boundary

MANIFEST.dcf identifies the installed SDK. gdalraster.windows-build.dcf identifies the SDK used for a package build. Comparing their bundle tags turns an ABI-sensitive update into an explicit state transition: a new SDK always requires a new gdalraster build.