Package 'gdalraster.windows'

Description

Prepends runtime paths, sets GDAL/PROJ env vars, and preloads GDAL DLL.

Usage

activate_gdal_runtime(
  gdal_home = default_gdal_home(),
  preload = TRUE,
  quiet = FALSE
)

Arguments

Details

When the runtime bundle contains a ⁠python/⁠ directory (pure-python osgeo_utils package from GDAL's gdal-utils distribution), it is prepended to PYTHONPATH so GDAL algorithms that embed Python at runtime (e.g. ⁠gdal driver gpkg validate⁠) can import it. This is session-scoped and does not modify machine or user environment variables.

When preload = TRUE and the GDAL DLL cannot be loaded (most commonly because a dependency DLL is missing), activation fails with an error rather than deferring the failure to library(gdalraster), where the Windows loader reports only a generic "module could not be found".

Value

Invisibly returns a list with configured paths.

Description

Writes a managed hook block into an .Rprofile file. The block loads the bundled GDAL DLL before package attach and prepends the custom gdalraster library path.

Usage

add_gdal_rprofile_hook(
  rprofile = "~/.Rprofile",
  gdal_home = default_gdal_home(),
  lib = default_gdalraster_lib(),
  dry_run = FALSE
)

Arguments

Value

Invisibly returns the updated .Rprofile text.

Description

Sets GDAL home for this session using either an R option or environment variable. This does not write to user profile files.

Usage

configure_gdal_home(path, mode = c("option", "env"))

Arguments

Value

Invisibly returns the normalized GDAL home path.

Description

Returns the currently configured GDAL runtime home used by this package.

Usage

gdal_home()

Details

Resolution order:

1. options(gdalraster.windows.gdal_home = "...")

2. GDALRASTER_WINDOWS_GDAL_HOME environment variable

3. package-managed user data directory (tools::R_user_dir())

Value

A single string path.

Description

Returns R code that loads the bundled GDAL DLL before attaching gdalraster, and prepends the custom lib path so library(gdalraster) resolves to the source build installed by install_gdalraster().

Usage

gdal_rprofile_snippet(
  gdal_home = default_gdal_home(),
  lib = default_gdalraster_lib()
)

Arguments

Value

A single string containing R code.

Description

Installs the GDAL runtime into gdal_home from one of:

Usage

install_gdal_runtime(
  repo = .bundle_repo,
  tag = "latest",
  asset_pattern = .bundle_asset_pattern,
  gdal_home = default_gdal_home(),
  overwrite = FALSE,
  local_zip = NULL,
  fallback_zip = NULL
)

Arguments

Details

• local_zip (highest precedence),

• GitHub release asset lookup/download,

• fallback_zip when release lookup/download fails.

The selected zip must contain a GDAL root with ⁠bin/libgdal-*.dll⁠.

Value

Invisibly returns installed GDAL home path.

Offline / air-gapped installation

On machines without network access, download the release asset manually from https://github.com/jimbrig/gdalraster.windows/releases, transfer it to the target machine, and install directly:

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

Note that no fallback zip is shipped with the package (a full runtime bundle is too large to vendor), so the fallback path only applies when you provide a fallback_zip yourself.

Overwriting an installed runtime

With overwrite = TRUE, the existing gdal_home is deleted before the new runtime is copied in. Runtime DLLs that were preloaded into the current session (the package auto-bootstrap does this at load time when a runtime is present) are unloaded first so the process does not block its own reinstall. This is not possible when gdalraster is loaded — its DLL pins the GDAL runtime in the process — so reinstalling then requires a fresh R session. Deletion is verified before copying: if another process holds locks on the runtime (another R session, a File Explorer preview pane), the install aborts cleanly instead of leaving a partially-replaced runtime.

Description

Downloads or uses a local gdalraster source tarball and installs it from source into a dedicated library path (default) so existing user libraries are not overwritten. To install into your regular user library instead (so plain library(gdalraster) resolves the source build without this package's load helpers), pass it explicitly, e.g. install_gdalraster(lib = .libPaths()[1]).

Usage

install_gdalraster(
  gdal_home = default_gdal_home(),
  lib = default_gdalraster_lib(),
  source_tarball = NULL,
  repo = .gdalraster_repo,
  ref = "HEAD",
  upgrade = FALSE,
  repos = getOption("repos")
)

Arguments

Value

Invisibly returns installed library path.

Prerequisites

This is a source compilation, so Rtools matching your R version must be installed (the one thing the prebuilt runtime bundle cannot eliminate). The function checks for a toolchain up front and aborts with guidance when none is found. The GDAL runtime bundle itself must already be installed via install_gdal_runtime().

Upgrading

After installing a new runtime bundle version (install_gdal_runtime(overwrite = TRUE)), rerun this function — the previous gdalraster build is bound to the previous bundle's GDAL and must be recompiled against the new one.

Description

Convenience wrapper over activate_gdal_runtime() that ensures the GDAL runtime is activated and the main GDAL DLL is preloaded in the current session.

Usage

load_gdal_dll(gdal_home = default_gdal_home(), quiet = FALSE)

Arguments

Value

Invisibly returns activation metadata.

Description

Activates bundled GDAL runtime, prepends lib to .libPaths(), and attaches gdalraster for use in the current R session.

Usage

load_gdalraster(
  lib = default_gdalraster_lib(),
  gdal_home = default_gdal_home(),
  quiet = FALSE
)

Arguments

Value

Invisibly returns TRUE if gdalraster was attached.

Description

Attempts to load gdalraster and checks the global algorithm registry.

Usage

verify_gdalraster_runtime(
  lib.loc = NULL,
  activate_runtime = TRUE,
  gdal_home = default_gdal_home(),
  quiet = FALSE
)

Arguments

Value

TRUE when algorithm API is available, otherwise FALSE (including when runtime activation itself fails).