17 Serving Package Binaries (Beta)

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 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.

17.1 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 Windows and Mac operating systems. RStudio Package Manager provides precompiled binaries for CRAN packages on specific Linux distributions:

  • Ubuntu 16.04 (Xenial)
  • Ubuntu 18.04 (Bionic)
  • CentOS/RHEL 7

RStudio Package Manager does not currently support binary packages for SUSE Linux, Windows, or Mac operating systems.

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 operating systems 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 operating system and version of R.

17.2 Binary Configuration Steps

By default, Package Manager will enable binary repository URLs and serve binary packages for the CRAN source for all supported Linux distributions. Administrators can customize the distributions that binaries are enabled for in the Package Manager configuration file.

To only offer binaries for certain distributions, use some combination of names:

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

To turn off support for binary packages altogether, use a blank value:

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

17.2.1 CRAN Package Binaries

RStudio pre-compiles the majority of CRAN packages for a combination of R versions and operating systems. RStudio Package Manager downloads the binaries from the RStudio CRAN service, respecting the same sync and download settings as the CRAN metadata. Note that eager fetching is only available for source packages at this time.

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:

17.2.2 Binaries for Other Package Manager Sources

At this time, binary packages are only supported for CRAN and “curated-cran” sources. Please contact support@rstudio.com if you are interested in building binaries for local or Git sources.

17.3 R Configuration Steps

17.3.1 Prerequisites

To use binary packages, an R user or RStudio Server 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:

  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 operating system 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.

17.3.2 Using Binary Packages

For each operating system that is enabled, RStudio Package Manager will add an additional repository URL to the repository Setup page on the web dashboard. For example, if Ubuntu 16.04 (Xenial) is enabled, users will have the option to pick between two repository URLs:

https://r-pkgs.example.com/our-cran/latest
https://r-pkgs.example.com/our-cran/__linux__/xenial/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 requests a package from the enabled __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 operating system, Package Manager falls back to serving the source version of the package.

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

After determining the checkpoint 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

When installing a binary package, R will print a message like this if the requested binary is available:

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

In the case that Package Manager falls back to serving source, R will print a message like:

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

17.3.3 Configuring the R User Agent Header

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

R users or RStudio Server 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:

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 operating system in the user agent header:

# 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:

# 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.

17.3.4 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:

$ 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__/xenial/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-xenial
X-Package-Type: binary

Or at an R console:

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