rig ppm

Ask Posit Package Manager (P3M) what it offers: which platforms and R versions it builds binary packages for, and which builds exist for a package. Nothing here changes anything on your machine.

rig ppm platforms and rig ppm r-versions list the build targets and R versions, rig ppm status shows P3M’s whole status report, rig ppm builds lists the published builds of one package, and rig ppm url prints the URL rig is talking to.

This is about P3M itself. To manage the repositories configured for your R installations, including P3M ones, use rig repos; to look up package metadata in those repositories, use rig pkg.

Which server

By default rig reports on the public instance, https://packagemanager.posit.co. Set the PACKAGEMANAGER_ADDRESS environment variable to the base URL of your own P3M instance to report on that instead. rig ppm url prints whichever one is in effect.

One command is different: rig ppm builds reads a package build index that rig publishes itself, derived from P3M, because P3M has no endpoint that lists a package’s builds. That index always comes from rig’s own host, and PACKAGEMANAGER_ADDRESS does not redirect it.

Subcommands

build-log

Show the P3M build log for a package

builds

List the published builds of a package

platforms

List the platforms Posit Package Manager builds for

r-versions

List the R versions Posit Package Manager builds for

status

Show the Posit Package Manager status report

url

Print the Posit Package Manager URL

rig ppm build-log

Fetch Posit Package Manager’s build log for one CRAN package: exit code, timings, system dependencies, and the compiler/build output. It is the diagnosis tool for “why is there no binary for this package on this platform” — a non-zero exit code or a missing system dependency in the log usually explains it.

--platform and --arch name the build target to look up: --platform is a P3M target name such as macos, windows, or a Linux codename like jammy (run rig ppm platforms or rig ppm builds to see the names P3M uses). Left unset, both default to the machine rig is running on. --r-version defaults to rig’s default R version (rig default), trimmed to a minor version (4.6.1 becomes 4.6) since that is all P3M accepts; pass it explicitly to ask about a different one. --version restricts the log to one package version; without it P3M reports the log for the latest version it knows.

P3M has no way to ask for the log of a specific historical rebuild: the log it serves is always for the current dependency snapshot of the requested distribution/architecture/R version/package version, recomputed on every request. So the same command run today and in a month can report different logs for what looks like the same build, if a dependency of the package has since changed. There is no flag to pin an older snapshot — P3M itself has no such endpoint.

Usage

rig ppm build-log [OPTIONS] <package>

Arguments

<package>

package whose build log to show

Options

--admin

Run in admin mode (overrides RIG_MODE and config)

-a, --arch <arch>

CPU architecture (default: the current architecture)

-h, --help

Print help (see a summary with ‘-h’)

--json

JSON output

--no-cache

Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)

-p, --platform <platform>

P3M build target, e.g. macos, windows, jammy (see rig ppm builds); default: the current platform

-r, --r-version <r-version>

R version the build is for (default: the default R version)

--user

Run in user mode (overrides RIG_MODE and config)

-v, --version <version>

package version (default: latest)

Examples

# The current platform, architecture and default R version
rig ppm build-log pak

# A specific target and package version
rig ppm build-log dplyr --platform jammy --r-version 4.5 --version 1.1.4

# Pick a target straight from `rig ppm builds`
rig ppm builds dplyr --json | jq '.[0] | {platform, arch, r_version}'

rig ppm builds

List every source and binary artifact Posit Package Manager has published for one R package, with the URL of each, oldest version first, so the latest version is the last thing printed. Use --version to restrict the listing to a single package version.

P3M has no endpoint that lists a package’s builds, so rig reads a build index it publishes itself, one compressed file per package, derived from P3M. That index comes from rig’s own host, and unlike the rest of rig ppm it is not affected by PACKAGEMANAGER_ADDRESS. Once fetched it is cached, so repeated queries about the same package are local.

The columns

• version — the package version, as published.

• platform — source for the CRAN source tarball, otherwise the build target: macos, windows, or a Linux target name such as jammy. rig ppm platforms lists the target names.

• arch, r_version — the architecture and minor R version the binary is for. Both are * on a source row, which is architecture- and version-independent.

• linkingto — the package versions the binary was compiled against, for packages with a LinkingTo: field. This column is what tells otherwise identical rows apart. P3M republishes a binary when a compiled-against dependency changes, so the same version, platform, architecture and R version can legitimately have several builds; linkingto is the only difference between them.

• url — where to download that artifact. The date in the URL is the CRAN snapshot the build was published against.

--json output adds a sha256 for each row, and for each linkingto entry. Be careful with it: it is the hash of the original CRAN source tarball, repeated on every platform row of a version. It is not the hash of the binary on that row, and not even the hash of what its own URL serves, because P3M rewrites the Repository: field of the DESCRIPTION before serving it. Treat it as an identity key for the upstream CRAN release, not as a checksum to verify a download against.

Usage

rig ppm builds [OPTIONS] <package>

Arguments

<package>

package to list the builds of

Options

--admin

Run in admin mode (overrides RIG_MODE and config)

-h, --help

Print help (see a summary with ‘-h’)

--json

JSON output

--no-cache

Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)

--user

Run in user mode (overrides RIG_MODE and config)

-v, --version <version>

package version to list (default: all)

Examples

# Every build of a package, latest version last
rig ppm builds cli

# Just one version
rig ppm builds dplyr --version 1.1.4

# The builds for one R version and platform
rig ppm builds dplyr --json |
  jq '.[] | select(.r_version == "4.5" and .platform == "jammy")'

rig ppm platforms

List the build targets Posit Package Manager currently offers.

P3M also reports the targets it has retired — on the public instance those are more than half of the list — and none of them is something to build against today, so they are left out. Add --all to list them too, with a hidden column marking which is which. --all applies to --json as well.

Apart from that the list is as P3M reports it: targets it serves but does not build binaries for are included, and the several entries that share one platform are not merged.

The columns

• name — P3M’s name for the entry.

• os — linux, macos or windows.

• platform — the name this target goes by in a package’s build index, so this is the value to match against the platform column of rig ppm builds. Several entries can share one: CentOS 7 and RHEL 7 both use the centos7 binaries.

• distribution and release — the distribution P3M builds the target on, which is not always the one it serves. The rhel9 target is built on Rocky Linux, so its distribution is rockylinux.

• arch — the architectures this target is built for. Most Linux targets are x86_64 only.

• binaries — whether P3M builds binary packages for the target at all. Where this is off, the target is still served, from source.

• hidden — only shown with --all: set on the targets P3M no longer advertises, i.e. retired distribution releases. Their binaries stay downloadable, which is why they can be listed at all.

The manylinux_2_28 target is the generic glibc build P3M serves to any Linux it has no specific target for. It appears under the distribution it happens to be built on, not the ones it serves.

rig reuses P3M’s status document for up to a day, so this command normally answers without contacting the server.

Usage

rig ppm platforms [OPTIONS]

Options

--admin

Run in admin mode (overrides RIG_MODE and config)

--all

Also list the platforms P3M has retired

-h, --help

Print help (see a summary with ‘-h’)

--json

JSON output

--no-cache

Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)

--user

Run in user mode (overrides RIG_MODE and config)

rig ppm r-versions

List the minor R versions Posit Package Manager builds binary packages for, newest first, one per line and without a header, so the output can be piped straight into other commands.

These are minor versions, e.g. 4.5, because that is the granularity R uses for binary compatibility: a package built for R 4.5 works with every R 4.5.x.

rig reuses P3M’s status document for up to a day, so this command normally answers without contacting the server.

Usage

rig ppm r-versions [OPTIONS]

Options

--admin

Run in admin mode (overrides RIG_MODE and config)

-h, --help

Print help (see a summary with ‘-h’)

--json

JSON output

--no-cache

Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)

--user

Run in user mode (overrides RIG_MODE and config)

rig ppm status

Show the full status report of a Posit Package Manager instance: what it is and what it is configured for, then the R versions, build targets, Bioconductor releases and macOS build flavors it serves.

The report

The first block is the instance itself: its version and build_date, the name of its CRAN repository, whether R and Python are configured, whether binary packages are enabled, whether it requires authentication, and how long its license still covers it.

Then four tables:

• R versions — the minor R versions binaries are built for. Same list as rig ppm r-versions.

• Build targets — the platforms, as reported, retired ones included. Same table as rig ppm platforms --all, which documents the columns.

• Bioconductor versions — each Bioconductor release, the R version it goes with, and the CRAN snapshot it is pinned to.

• macOS binaries — the macOS build flavor used for each R version, per architecture. default is what a newer R version gets. An empty cell means there are no macOS binaries for that R version and architecture.

An instance may report fields rig does not show. Use --json to see the status document in full; nothing is dropped from it.

Unlike the other rig ppm commands, this one always contacts the server, because part of what it reports is live state. It therefore needs network access even when the other commands do not.

Which server

https://packagemanager.posit.co by default, or the instance PACKAGEMANAGER_ADDRESS names. RIG_PPM_STATUS_URL overrides the URL of the status document alone and wins over PACKAGEMANAGER_ADDRESS; the report’s first line shows the URL actually used.

Usage

rig ppm status [OPTIONS]

Options

--admin

Run in admin mode (overrides RIG_MODE and config)

-h, --help

Print help (see a summary with ‘-h’)

--json

JSON output

--no-cache

Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)

--user

Run in user mode (overrides RIG_MODE and config)

Examples

# The public instance
rig ppm status

# Your own instance
PACKAGEMANAGER_ADDRESS=https://ppm.example.com rig ppm status

# The complete status document, including fields rig does not display
rig ppm status --json

rig ppm url

Print the base URL of the Posit Package Manager instance the other rig ppm commands report on, and nothing else, so it can be used directly in a script:

curl "$(rig ppm url)/__api__/repos"

This is https://packagemanager.posit.co unless the PACKAGEMANAGER_ADDRESS environment variable is set, in which case it is that, with any trailing slash removed.

The RIG_PPM_STATUS_URL environment variable overrides the URL of the status document alone, and takes precedence over PACKAGEMANAGER_ADDRESS for that one document. If you set it, this command still prints the base URL, while rig ppm status reports on the instance RIG_PPM_STATUS_URL names and shows which URL that was.

Usage

rig ppm url [OPTIONS]

Options

--admin

Run in admin mode (overrides RIG_MODE and config)

-h, --help

Print help (see a summary with ‘-h’)

--json

JSON output

--no-cache

Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)

--user

Run in user mode (overrides RIG_MODE and config)