---
title: "FAQ and troubleshooting"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{FAQ and troubleshooting}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

This vignette collects answers to common questions that come up when using
`sysreqr` or, more generally, when installing R packages from source on
GNU/Linux.

## My install failed but `sysreqr` reports nothing missing

Not every install failure is caused by a missing system library. Other
causes:

* **R version too old.** Some CRAN packages require recent R. Run
  `R.version.string`.
* **Package source too old.** A pinned older package version may need a
  library you no longer have at that version. Try a newer package version.
* **Disk full or read-only library path.** Check with `df -h` and
  `.libPaths()`.
* **Network failure mid-download.** Re-run.
* **Locked package.** A `00LOCK-<name>` directory in your library path from
  a previous failed install. Remove it.

When in doubt, run `setup_advice()` to confirm the broader checklist, then
ask for help with the specific log.

## I'm on a server without `sudo`. What now?

Use `admin_request()` to draft a message you can send to your administrator:

```r
plan <- check_packages(c("xml2", "curl"), platform = "ubuntu-22.04")
cat(admin_request(plan))
```

The message lists the missing system packages, which R packages need them,
and the exact install command. Many administrators appreciate having all of
that in one place.

## How does `sysreqr` differ from `pak`, `remotes`, and `renv`?

| Tool                          | Strengths                                          | Limitations                                  |
|-------------------------------|----------------------------------------------------|----------------------------------------------|
| `pak::pkg_sysreqs()`          | Authoritative live resolver                        | Requires `pak`; no log diagnosis             |
| `remotes::system_requirements()` | Light; widely available                         | No log diagnosis, no project scanner         |
| `renv::sysreqs()`             | Project-oriented; integrates with `renv` workflow  | Requires `renv`                              |
| `sysreqr`                     | Zero runtime deps; log diagnosis; beginner UX      | Bundled DB is small; biased to `apt`         |

`sysreqr` can use `pak` as one of its backends (`backend = "pak"`) when it
is installed. The two tools are complementary, not competitors.

## I'm in Docker and platform detection seems wrong

When you run `detect_platform()` *outside* a container, R sees the host
operating system. When you run it *inside* a container, R sees the container
operating system. If you are generating a Dockerfile from your laptop for a
different base image, always specify the `platform` argument explicitly:

```r
dockerfile(check_packages("xml2", platform = "ubuntu-22.04"))
```

See the Docker vignette for more detail.

## How do I keep the bundled database current?

The bundled database is refreshed with each package release. There is no
runtime "update" function, because CRAN policy forbids packages from
writing to their installed location.

If you need newer data than the latest release, use
`backend = "ppm"` for live Posit Package Manager data, or `backend = "pak"`
for live `pak` resolution.

## Why is `sysreqr` suggesting `r-base-dev`?

`r-base-dev` is the Debian/Ubuntu package that contains the development
headers and Makefile fragments needed to compile R packages from source.
You only need it if you build R packages from source (which is the default
on Linux). `setup_advice()` includes it in the build-tools step.

On Fedora/RHEL, the equivalent comes with the `R` package itself. On
openSUSE, the equivalent is `R-base`.

## I'm on Alpine. What's supported?

Alpine uses `apk` and is detected as `alpine`. Install commands use
`apk add --no-cache`. The bundled fallback database currently uses
Debian/Ubuntu names, so prefer the `ppm` or `pak` backend on Alpine. Many
common system libraries on Alpine are in the
[community repository](https://pkgs.alpinelinux.org/packages?branch=v3.20&repo=community).

## I'm behind a corporate proxy. PPM queries fail

Posit Package Manager queries use `utils::download.file()`. Set the
standard `http_proxy` and `https_proxy` environment variables before
starting R, or configure them in your `.Renviron`.

If outbound HTTP is blocked entirely, use `backend = "bundled"` or
`backend = "pak"` (pak has its own download tooling and may already be
configured for your network).

## What do the confidence levels mean?

* **`high`**: direct evidence: a missing-header or linker error pattern was
  matched in the log, or live upstream metadata reported the requirement.
* **`medium`**: indirect evidence: a tool failure (such as `pkg-config not
  found`) or a failed-package lookup against the bundled fallback database.
* **`low`**: reserved for future, broader heuristics.

A medium-confidence result is still useful, but it is not proof. R version
mismatches, locked libraries, and permission problems can all cause failed
installs unrelated to system requirements.

## `sysreqr` says the platform is unsupported but I want to try anyway

Use the `platform` argument with an explicit platform string. If you supply
`backend = "ppm"`, the package will ask Posit Package Manager which is
authoritative.

If you are experimenting with an unknown platform, please open an issue at
<https://github.com/choxos/sysreqR/issues> with the contents of
`/etc/os-release` so support can be added properly.

## Why does this package use a custom JSON parser?

A small custom parser keeps the package free of runtime dependencies, in
line with its design goal. `jsonlite` would also work, but it would add a
dependency that the rest of the package does not need. The parser is
exercised by the test suite and handles unicode escapes, nested arrays, and
the JSON dialect used by Posit Package Manager and `renv.lock`.

## See also

* `vignette("preflight-setup")` for the preventive workflow.
* `vignette("diagnosing-failures")` for log diagnosis.
* `vignette("linux-fundamentals")` for GNU/Linux background.
* `vignette("docker-and-ci")` for container and CI workflows.