---
title: "Using gdalraster.windows on Windows"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Using gdalraster.windows on Windows}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

## 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

```{r eval = FALSE}
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:

```{r eval = FALSE}
library(gdalraster.windows)
library(gdalraster)
gdalraster::gdal_global_reg_names()
```

Explicit load flow:

```{r eval = FALSE}
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:

```{r eval = FALSE}
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).

```{r eval = FALSE}
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:

```{r eval = FALSE}
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

- `dev/docs/06-toolchain-and-abi.md`
- <https://github.com/firelab/gdalraster/issues/826>
- <https://github.com/firelab/gdalraster/issues/858>
- <https://github.com/firelab/gdalraster/issues/982>
- <https://github.com/OSGeo/gdal/pull/13592>