rig system

Various commands to modify and configure the installed R versions. See their help pages for details. E.g. run rig system make-links --help.

Subcommands

add-pak
Install or update pak for an R version
allow-core-dumps macOS only
Allow creating core dumps when R crashes
allow-debugger macOS only
Allow debugging R with lldb and gdb
allow-debugger-rstudio macOS only
Allow debugging RStudio with lldb and gdb
clean-registry Windows only
Clean stale R related entries in the registry
detect-platform
Detect operating system version and distribution.
dirs
Print the directories rig uses
fix-permissions macOS only
Restrict system library permissions to admin
fix-r-alias Windows only
Make the ‘R’ command start R in PowerShell
forget macOS only
Make system forget about R installations
make-links
Create R-* quick links
make-orthogonal macOS only
Make installed versions orthogonal
no-openmp macOS only
Remove OpenMP (-fopenmp) option for Apple compilers
setup-user-lib
Set up automatic user package libraries (alias: create-lib)
update-certs Linux only
Download the CA certificate bundle and configure R to use it
update-rtools40 Windows only
Update Rtools40 MSYS2 packages
user-mode
Switch to user mode and clean up admin-mode installations

rig system add-pak

Install/update pak for one or more R versions.

  • If --all is specified, then it installs pak for all current R installations.
  • If one or more R versions are specified, then it installs pak for those.
  • If no R versions are specified, then it installs pak for the default R installation, if there is one (see rig default).

Usage

rig system add-pak [OPTIONS] [version]...

Arguments

[version]...
R versions to install/update pak for

Options

--admin
Run in admin mode (overrides RIG_MODE and config)
--all
Install pak for all R versions
--devel
Install the development version of pak (deprecated)
-h, --help
Print help (see a summary with ‘-h’)
--no-cache
Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)
--pak-version <pak-version>
pak version to install. [default: stable]
[possible values: stable, devel]
--user
Run in user mode (overrides RIG_MODE and config)

rig system allow-core-dumps macOS only

Update the entitlements of the R process to allow core dumps on macOS. This command is similar to rig system allow-debugger but it also makes sure that the /cores directory of core dumps is writeable by the current user. Don’t forget to call ulimit -c unlimited from the same shell before starting R.

This command does nothing on Windows and Linux and in user mode.

In admin mode this command probably needs sudo: sudo rig system allow-core-dumps, otherwise rig will ask for your password.

Usage

rig system allow-core-dumps [OPTIONS] [version]...

Arguments

[version]...
R versions to update (default is the default R version)

Options

--admin
Run in admin mode (overrides RIG_MODE and config)
--all
Update all R versions
-h, --help
Print help (see a summary with ‘-h’)
--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 system allow-debugger macOS only

Update the entitlements of the R binary to allow debuggers on macOS. It adds the get-task-allow entitlement to the R binary. This is only needed for R installers 3.6 and later, previous versions are not signed. Call R -d lldb to start lldb on R. (Or R-x.y -d lldb if you want a non-default version.)

See also rig system allow-debugger-rstudio, which does the same for R running in RStudio.

This command does nothing on Windows and Linux and in user mode.

In admin mode this command probably needs sudo: sudo rig system allow-debugger, otherwise rig will ask for your password.

Usage

rig system allow-debugger [OPTIONS] [version]...

Arguments

[version]...
R versions to update (default is the default R version)

Options

--admin
Run in admin mode (overrides RIG_MODE and config)
--all
Update all R versions
-h, --help
Print help (see a summary with ‘-h’)
--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 system allow-debugger-rstudio macOS only

Update the entitlements of RStudio R process to allow debuggers on macOS. It adds the get-task-allow entitlement to the rsession (and rsession-arm64 on arm64 hardware) binary.

See also rig system allow-debugger, which does the same for R running outside of RStudio.

This command does nothing on Windows and Linux.

This command probably needs sudo: sudo rig system allow-debugger-rstudio, otherwise rig will ask for your password.

Usage

rig system allow-debugger-rstudio [OPTIONS]

Options

--admin
Run in admin mode (overrides RIG_MODE and config)
-h, --help
Print help (see a summary with ‘-h’)
--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 system clean-registry Windows only

Remove R and Rtools entries from the Windows registry, if the corresponding R or Rtools versions are not installed any more.

This command does nothing on macOS and Linux.

Usage

rig system clean-registry [OPTIONS]

Options

--admin
Run in admin mode (overrides RIG_MODE and config)
-h, --help
Print help (see a summary with ‘-h’)
--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 system detect-platform

Detect and print the operating system version and distribution.

rig uses this information to choose the right R builds and package repositories. Use --json for machine-readable output.

Usage

rig system detect-platform [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 system dirs

Print the directories rig uses: where R and (on Windows) Rtools is installed, where the quick links are created, where (on Linux) rig keeps the fontconfig configuration and the fallback fonts of the portable R builds, where rig downloads the installers to, and where rig keeps its own configuration, data, cache and log files.

The directories themselves may not exist.

Use --json for machine-readable output.

The output contains the directories in effect. They may be the defaults, or configured via the rig config file or environment variables.

Some directories may depend on the mode and on the architecture, e.g. on aarch64 Windows the R installation directory is different for aarch64 and x86_64 R builds.

Use --user and --admin to override the mode for a single invocation.

Printing a single directory

With one of the flags (see below) rig prints that single directory as a bare path, and nothing else, for use in a shell script:

cd "$(rig system dirs --r)"

The flags are mutually exclusive, and cannot be combined with --json.

--r is the directory that contains the directories of the individual R versions; it is not an R installation itself. Similarly --rtools is the directory that contains the Rtools directories. Use rig list --json and rig rtools list for the paths of the installed versions.

The Rtools installation root is only reported on Windows. On non-Windows platforms --rtools prints nothing and is hidden.

The fontconfig directory is only reported on Linux, where it holds the fonts.conf and the fallback fonts that rig installs for the portable R builds. On non-Linux platforms --fonts prints nothing and is hidden.

--download is the directory rig downloads the installers into. It is in the system temporary directory and its name contains your user id, so that admin and user mode installs, and different users of the same machine, never share it. See the download-dir configuration entry to change it.

Usage

rig system dirs [OPTIONS]

Options

--admin
Run in admin mode (overrides RIG_MODE and config)
-a, --arch <arch> Windows only
Architecture of the R installation root (default: native arch). [possible values: x86_64, aarch64, arm64]
--binary
Print the quick link directory only.
--cache
Print rig’s cache directory only.
--data
Print rig’s data directory only.
--download
Print rig’s installer download directory only.
--fonts Linux only
Print the fontconfig directory only.
-h, --help
Print help (see a summary with ‘-h’)
--json
JSON output
--log
Print rig’s log directory only.
--no-cache
Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)
--r
Print the R installation root only.
--rtools Windows only
Print the Rtools installation root only.
--user
Run in user mode (overrides RIG_MODE and config)

rig system fix-permissions macOS only

Update the permissions of the current R versions on macOS, so only the administrator can install R packages into the system library. Together with rig system setup-user-lib this facilitates keeping additional packages in a user library, instead of the system library.

This command does nothing on Windows and Linux and in user mode.

rig add runs rig system fix-permissions, so if you only use rig to install R, then you do not need to run it manually.

In admin mode this command probably needs sudo: sudo rig system fix-permissions, otherwise rig will ask for your password.

Usage

rig system fix-permissions [OPTIONS] [version]...

Arguments

[version]...
R versions to update (default: all)

Options

--admin
Run in admin mode (overrides RIG_MODE and config)
-h, --help
Print help (see a summary with ‘-h’)
--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 system fix-r-alias Windows only

Make the ‘R’ command start R in PowerShell.

PowerShell ships a built-in ‘r’ alias for ‘Invoke-History’, and because aliases take precedence over external commands, typing ‘R’ reruns the previous command instead of starting R. This command removes that alias in your PowerShell profile so that ‘R’ starts R via rig’s quick link.

It edits the ‘CurrentUserAllHosts’ profile of every PowerShell it finds (both ‘pwsh’ and ‘powershell’), in an idempotent, clearly marked block. Start a new PowerShell session for the change to take effect.

Use the ‘–undo’ flag to remove the block rig added, leaving the rest of the PowerShell profile(s) untouched.

This command does nothing on macOS and Linux.

Usage

rig system fix-r-alias [OPTIONS]

Options

--admin
Run in admin mode (overrides RIG_MODE and config)
-h, --help
Print help (see a summary with ‘-h’)
--no-cache
Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)
--undo
Remove the block rig added to the PowerShell profile(s).
--user
Run in user mode (overrides RIG_MODE and config)

rig system forget macOS only

Tell macOS to forget about the currently installed R versions. This is needed to have multiple R installations at the same time.

This command does nothing on Windows and Linux and in user mode.

rig add runs rig system forget before and after the installation, so if you only use rig to install R, then you don’t need to run this command manually.

In admin mode this command probably needs sudo: sudo rig system forget, otherwise rig will ask for your password.

Usage

rig system forget [OPTIONS]

Options

--admin
Run in admin mode (overrides RIG_MODE and config)
-h, --help
Print help (see a summary with ‘-h’)
--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 system make-orthogonal macOS only

Make the current R installations orthogonal on macOS. This allows running multiple R versions at the same time.

This command does nothing on Windows and Linux, where R installations are automatically orthogonal. It also does nothing in user mode, as user mode installations are always orthogonal.

rig add runs rig system make-orthogonal automatically, you do not need to run it manually.

In admin mode this command probably needs sudo: sudo rig system make-orthogonal, otherwise rig will ask for your password.

Usage

rig system make-orthogonal [OPTIONS] [version]...

Arguments

[version]...
R versions to update (default: all)

Options

--admin
Run in admin mode (overrides RIG_MODE and config)
-h, --help
Print help (see a summary with ‘-h’)
--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 system no-openmp macOS only

Remove -fopenmp flags from the R configuration, to make R work with the Apple compilers, instead of CRAN’s custom compilers. This is only needed for R 3.6.x and before.

rig add runs rig system no-openmp after the installation, so if only use rig to install R, then you don’t need to run this command manually.

This command does nothing on Windows and Linux and in user mode.

In admin mode this command probably needs sudo: sudo rig system no-openmp, otherwise rig will ask for your password.

Usage

rig system no-openmp [OPTIONS] [version]...

Arguments

[version]...
R versions to update (default: all)

Options

--admin
Run in admin mode (overrides RIG_MODE and config)
-h, --help
Print help (see a summary with ‘-h’)
--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 system setup-user-lib

Alias: rig system create-lib

Set up R to create user package libraries when started, by default for installed R versions.

rig add runs rig system setup-user-lib, so if you only use rig to install R, then you do not need to run it manually.

Usage

rig system setup-user-lib [OPTIONS] [version]...

Arguments

[version]...
R versions (default: all)

Options

--admin
Run in admin mode (overrides RIG_MODE and config)
-h, --help
Print help (see a summary with ‘-h’)
--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 system update-certs Linux only

Download the CA certificate bundle and configure R to use it (Linux only).

This helps R make HTTPS connections on systems where the default certificate store is missing or out of date.

Usage

rig system update-certs [OPTIONS]

Options

--admin
Run in admin mode (overrides RIG_MODE and config)
-h, --help
Print help (see a summary with ‘-h’)
--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 system update-rtools40 Windows only

Update Rtools40 compilers and libraries to the latest builds by updating the MSYS2 packages in Rtools40 on Windows.

This command does nothing on macOS and Linux.

In admin mode this command needs an administrator account.

Usage

rig system update-rtools40 [OPTIONS]

Options

--admin
Run in admin mode (overrides RIG_MODE and config)
-h, --help
Print help (see a summary with ‘-h’)
--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 system user-mode

Switch rig to user mode and clean up the machine after admin mode.

In user mode rig installs R into your home directory (~/.local/share/rig/r or %APPDATA%\rig\data\r on Windows), and quick links into ~/.local/bin, so that rig never needs sudo. This command migrates an existing admin-mode setup to user mode:

  1. Sets the rig mode configuration to user.
  2. Reinstalls the admin-mode R versions in user mode, and restores the previous default version and version aliases. R versions that are already installed in user mode are not reinstalled. Use --no-reinstall to skip this step entirely and only clean up.
  3. Removes the system-wide admin-mode R installations.
  4. Removes the system-wide R-* quick links and the R/Rscript links.

Steps 3 and 4 remove files outside your home directory, so this command needs an administrator account or sudo on Unix, otherwise it will ask for your password.

Note that admin mode is rig’s default and the better tested mode, so there is no need to switch a working admin-mode setup. On Linux in particular, user mode uses portable (manylinux or musl) R builds and manylinux R packages, which are newer and less tested than the distro-specific builds and packages of admin mode. To go back to admin mode, run rig config set mode=admin and reinstall the R versions you want.

Use --keep-install to leave the admin-mode R installations in place (skipping step 3), and --keep-links to leave the system-wide links in place (skipping step 4). With both, nothing outside your home directory is touched and no administrator account or sudo is needed.

Usage

rig system user-mode [OPTIONS]

Options

-h, --help
Print help (see a summary with ‘-h’)
--keep-install
Keep the admin-mode R installations, do not remove them.
--keep-links
Keep the admin-mode quick links, do not remove them.
--no-cache
Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)
--no-reinstall
Do not reinstall admin-mode R versions in user mode.