Serving Package Binaries#

R packages come in a variety of formats:

• Source: A collection of directories and files containing source code.
• Bundle: A TAR file containing the bundled source code. This file is the result of running R CMD build for that R package.
• Binary: A binary file specific to an operating system (OS) and architecture, containing compiled source code. Not an executable. The result of R CMD INSTALL.

For more information, see Wickham's book, R Packages.

RStudio Package Manager helps package developers transform packages between formats, and it also can serve different package formats to R users.

Binary Packages#

The binary format of an R package is useful because an R user can install a binary package without compiling all of the package's source code. In some cases source packages can take hours to install. Additionally, compiling package binaries requires locating and installing system prerequisites. RStudio Package Manager binary support can eliminate this burden of waiting for packages to compile.

Traditionally, public CRAN mirrors have made binary packages available for the Windows and Mac operating systems. RStudio Package Manager provides precompiled binaries for CRAN packages for both Windows and Linux.

When enabled, Package Manager will serve the appropriate binaries to R users instead of the source packages, saving R users significant installation time. Binary packages are specific to the OS and R versions used to generate them. Package Manager is careful to supply the correct binaries based on its configuration settings and the user's indicated OS and version of R.

Supported Operating Systems#

RStudio Package Manager supports binary packages for Windows and the following Linux distributions:

• Ubuntu 16.04 (Xenial)*
• Ubuntu 18.04 (Bionic)
• Ubuntu 20.04 (Focal)
• CentOS/RHEL 7
• CentOS/RHEL 8
• openSUSE 42.3*, SLES 12 SP5
• openSUSE 15.1*, SLES 15 SP1*
• openSUSE 15.2, SLES 15 SP2

When an operating system has reached its end of support, RStudio Package Manager will continue to serve binary packages for that operating system in perpetuity, but no longer provide new binary packages after several months. Refer to the RStudio Platform Support page for the vendor end-of-support dates.

Supported R Versions#

RStudio Package Manager supports binary packages for the current R version and the four previous versions of R.

When an R version is no longer supported, RStudio Package Manager will continue to serve binary packages for that R version in perpetuity, but no longer provide new binary packages after several months.

Binaries for Other Package Manager Sources#

At this time, binary packages are only supported for CRAN, curated CRAN, and CRAN snapshot sources. Please contact support@rstudio.com if you are interested in binary packages for local, Git, or Bioconductor sources.

Binary Configuration Steps#

By default, Package Manager will enable binary repository URLs and serve binary packages for the CRAN Source for Windows and all supported Linux distributions. Administrators can restrict the distributions that binaries are enabled for using the CRAN.Binaries configuration setting.

To serve binaries for certain distributions only, use a comma-separated list of names, such as:

; /etc/rstudio-pm/rstudio-pm.gcfg
[CRAN]
Binaries = "centos7, centos8"

To disable support for binary packages, use a blank value:

; /etc/rstudio-pm/rstudio-pm.gcfg
[CRAN]
Binaries = ""

CRAN Package Binaries#

RStudio pre-compiles the majority of CRAN packages for a combination of R versions and OSs. RStudio Package Manager downloads the binaries from the RStudio CRAN service, respecting the same sync and download settings as the CRAN metadata.

The RStudio CRAN service builds binary packages using open source R binaries and Docker images. To ensure that the binary packages are compatible with your client systems, we recommend using the same R binaries or Docker images:

• RStudio R Binaries
• RStudio R Docker Images

R Configuration Steps (Linux)#

Prerequisites#

To use binary packages, an R user or RStudio Workbench, formerly RStudio Server Pro, administrator should follow these steps to prepare and configure their environment:

1. Ensure that R is compatible with the precompiled binary packages. Binary packages distributed by RStudio Package Manager should be compatible with the default R on supported Linux distributions. However, the best way to ensure compatibility is to use the same R installation used to build the binary packages. RStudio provides precompiled R binaries and Docker images for supported Linux distributions:

   • RStudio R Binaries
   • RStudio R Docker Images

2. If using R 3.6 or a non-default download method such as "curl" or "wget", ensure that R correctly reports the R version and OS in the user agent header.

   See Configuring the User Agent Header for instructions.

3. Install system dependencies used by your R packages. Although binary packages are precompiled, you may still need system dependencies used at runtime.

   See System Dependency Detection for details on locating and installing system dependencies.

Using Linux Binary Packages#

For each Linux operating system that is enabled, RStudio Package Manager adds another repository URL to the repository Setup page on the web dashboard. For example, if Ubuntu 20.04 (Focal) is enabled, users have the option to pick between two repository URLs:

Terminal

https://r-pkgs.example.com/our-cran/latest
https://r-pkgs.example.com/our-cran/__linux__/focal/latest

To access binaries, use the second URL when configuring the repo option in R. Alternatively, administrators can use the second URL when configuring RStudio Server to use Package Manager.

When a user installs a package from the __linux__ URL, Package Manager will make a best-effort attempt to return a binary package. In cases where the binary package is unavailable or unsupported on the user's OS, Package Manager falls back to serving the source version of the package.

Like the default URL, the enabled __linux__ URL also supports snapshots in addition to the latest flag.

After determining the snapshot on the Setup page in the Package Manager UI, you may use a URL like this to configure the repo option in R.

https://r-pkgs.example.com/our-cran/__linux__/centos7/695

To install binary packages, users should run install.packages() using the default type argument (not type = "binary"). For example, to install the dplyr package:

install.packages("dplyr")

If the binary package installation succeeded, R should print a message like this:

* installing *binary* package 'dplyr' ...

If the binary package was unavailable or unsupported, Package Manager should fall back to serving a source package:

* installing *source* package 'dplyr' ...

Configuring the R User Agent Header#

Package Manager serves the appropriate binary package based on the R version and OS in the user's User-Agent request header.

R users or RStudio Workbench admins may need to additionally configure the user agent in R if using:

• R 3.6 or later
• A non-default download method such as "curl" or "wget"

To determine if you need to configure the user agent header, you can run this diagnostic script. You can either download and run this script in R, or run it directly from an R console:

Terminal

source("check-user-agent.R")

If your user agent is configured correctly, you should see a message like this:

Success! Your user agent is correctly configured.

If this diagnostic fails, R should be configured to include the R version and OS in the user agent header:

R

# Set the default HTTP user agent
options(HTTPUserAgent = sprintf("R/%s R (%s)", getRversion(), paste(getRversion(), R.version["platform"], R.version["arch"], R.version["os"])))

To use binary packages with a non-default download method such as "curl" or "wget", R should be configured to include the R version and operating system in the user agent header:

R

# Set the default HTTP user agent
options(download.file.extra = sprintf("--header \"User-Agent: R (%s)\"", paste(getRversion(), R.version["platform"], R.version["arch"], R.version["os"])))

We recommend adding this to the site-wide startup file (Rprofile.site) or user startup file (.Rprofile), so that R always starts with the correct configuration.

After configuring your user agent, you can re-run the diagnostic script to verify whether it is configured correctly by running this diagnostic script.

Troubleshooting#

The Service Log provides a record of package installation requests to Package Manager. When enabled, administrators can use the Service Log to determine why a user received a source package when installing from a binary repository URL.

Package Manager also returns one or two HTTP response headers that can help explain what type of package was served:

• X-Package-Type - indicates either binary or source
• X-Package-Binary-Tag - indicates the R version and distribution associated with the binary that was served. This only appears when a binary is served.

For example, you can test on the Linux command line with a request like:

Terminal

$ curl -H "User-Agent: R (3.5.3 x86_64-pc-linux-gnu x86_64 linux-gnu)" -I https://r-pkgs.example.com/our-cran/__linux__/focal/latest/src/contrib/A3_1.0.0.tar.gz
<< HTTP/1.1 200 OK
<< Content-Length: 87490
<< Content-Type: application/x-gzip
<< X-Package-Binary-Tag: 3.5-focal
<< X-Package-Type: binary

Or at an R console:

> curlGetHeaders("https://r-pkgs.example.com/our-cran/__linux__/focal/latest/src/contrib/A3_1.0.0.tar.gz")
# ...
# [10] "X-Package-Binary-Tag: 3.5-focal\r\n"
# [11] "X-Package-Type: binary\r\n"

R Configuration Steps (Windows)#

Prerequisites#

To use binary packages, an R user should follow these steps to prepare and configure their environment:

1. Ensure that R is compatible with the precompiled binary packages. Binary packages distributed by RStudio Package Manager should be compatible with the default R on Windows OSs.

2. Install system dependencies used by your R packages. Although binary packages are precompiled, you may still need system dependencies used at runtime.

For more information see the CRAN documentation for installing R packages on Windows.

Using Windows Binary Packages#

For Windows binary packages, users take advantage of the same URL they use for source packages. For example, if the repository is called our-cran, then users will want to use the following repository URL to install packages (from the latest snapshot):

Terminal

https://r-pkgs.example.com/our-cran/latest

You'll see R print the same messages indicating if the user received a binary or source package from RStudio Package Manager.

If only the source package is available you'll sometimes see:

install.packages('example-package', repos='https://r-pkgs.example.com/our-cran/latest')
<< Package which is only available in source form, and may need
<<   compilation of [example-system-dependency]: 'text2vec'
<< Do you want to attempt to install these from sources? (Yes/no/cancel)

This means additional system dependencies are required for the installation.

It is important to note that RStudio Package Manager makes a best effort to use the same compatibility requirements as CRAN. For more information see the CRAN documentation on installing R packages on Windows.