GNU/Linux fundamentals for R users

What is a Linux distribution?

A Linux distribution (or distro) bundles the Linux kernel with a set of user-space tools, a package manager, default configurations, and a release schedule. The distribution is what you actually install on a server or workstation.

R cares about distributions because:

• The system packages it needs (libraries, headers, compilers) come from the distribution’s package manager, not from CRAN.
• Each distribution has its own naming conventions for the same library.
• Each distribution has its own release cycle and its own snapshot of available software.

The distributions sysreqr understands well:

• Ubuntu (Debian-derived; LTS releases every two years). Codenames you will see: jammy (22.04), noble (24.04), resolute (26.04).
• Debian (the upstream). Codenames: bookworm (12), trixie (13).
• Red Hat Enterprise Linux (RHEL) and binary-compatible rebuilds: Rocky Linux, AlmaLinux.
• Fedora (Red Hat’s upstream, fast-moving).
• CentOS 7 (legacy; the CentOS Stream model replaced it).
• openSUSE and SUSE Linux Enterprise (SLE).
• Alpine (small, common in Docker images).

Package managers

A package manager installs, updates, and removes system software from a trusted repository.

sysreqr outputs commands that match the platform’s package manager.

sudo and root

Most distributions ship with a root (administrator) account that owns system files. Regular users cannot install system packages directly. The sudo command runs one command as root, after asking for the user’s password.

sudo apt-get install -y libxml2-dev

You will see sudo in every install command sysreqr generates that touches system state. Two important consequences:

1. If you are on a shared server without sudo, you cannot install system packages yourself. Use admin_request() to draft a message to your administrator instead.
2. sudo does not make R CMD install itself need root. Library paths inside the user’s home directory should not be installed as root.

The -dev and -devel story

R packages that compile from source need development headers, the .h files that describe a library’s interface. On Debian and Ubuntu, the header package has the -dev suffix; on Fedora-style systems, -devel.

For libxml2:

sysreqr will pick the right name for the platform. Sometimes a CRAN package needs both a runtime library and a separate tool (like pkg-config); the plan reports each one.

pkg-config

When an R package is built from source, the build script asks pkg-config where to find the system library. pkg-config reads small .pc files that each -dev / -devel package installs.

A typical sign of a missing -dev package is an R build error like:

Package libxml-2.0 was not found in the pkg-config search path.
Perhaps you should add the directory containing `libxml-2.0.pc'
to the PKG_CONFIG_PATH environment variable.

sysreqr::diagnose_log() will translate this back to the missing system package.

Binaries vs. source

CRAN serves source tarballs. When R installs xml2 from source, it may:

• Download a pre-built binary appropriate to your OS and R version (typical on Windows and macOS), or
• Download the source and compile it locally (typical on Linux).

Compiling from source is where most “missing system library” failures come from. Two strategies to avoid them:

1. Use binary R packages: on Linux, point R at the Posit Package Manager binary repository for your distribution. sysreqr::use_ppm() produces the .Rprofile lines for that.
2. Install the right -dev packages first: sysreqr::setup_advice() and sysreqr::check_packages() will list them.

How sysreqr fits in

sysreqr does not run sudo, does not edit operating system files, and does not install anything. It:

• detects your platform,
• tells you what system packages you (or your administrator) need to install,
• prints an exact command for your distribution,
• writes that command to a reviewable script when you ask it to,
• generates Dockerfile or GitHub Actions snippets when you want to automate.

You stay in control.

Common gotchas

• Forgetting apt-get update. On Debian-derived systems, the package list is cached. After a fresh container start, or after the cache expires, apt-get install will fail until you refresh.
• Slim Docker images. Images like rocker/r-ver use --no-install-recommends to keep the image small. The Dockerfile snippet emitted by sysreqr::dockerfile() follows the same pattern.
• pkg-config not installed. Many R packages assume it is present. setup_advice() adds it to the build-tools step.
• Mixing R sources. Installing R from the distribution repository and from the R Project repository at the same time can lead to two different R installations with two different libraries. Pick one.
• Inside a container, the host’s package manager is irrelevant. If you are building a Docker image from rocker/r-ver:4.4, the container is Debian-based, even if your laptop runs Fedora. Always specify the platform argument to sysreqr functions when working inside a container.

Glossary

• Codename: a memorable name for a distribution version, e.g. noble for Ubuntu 24.04.
• LTS: long-term support. Ubuntu LTS releases (22.04, 24.04, 26.04, …) get five years of free updates.
• CRAN: the Comprehensive R Archive Network, where R packages come from.
• Repository (apt): a server with .deb packages.
• Repository (dnf): a server with .rpm packages.
• Repository (R): a server with R package tarballs.
• -dev / -devel: package suffix for development headers.
• pkg-config: a helper used during builds to locate system libraries.
• sudo: command that runs one command as root.

See also

• vignette("preflight-setup") for the standard preflight workflow.
• vignette("docker-and-ci") for container and CI workflows.
• vignette("faq") for frequently asked questions.