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 Windows and MacOS. RStudio Package Manager provides precompiled binaries for CRAN packages for both the Windows OS and specific Linux distributions:

Ubuntu 16.04 (Xenial)
Ubuntu 18.04 (Bionic)
CentOS/RHEL 7
CentOS/RHEL 8
openSUSE 42/SLES 12
openSUSE 15/SLES 15

RStudio Package Manager does not support binary packages for MacOS.

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.

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 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, centos8, opensuse42, opensuse15, windows"

To turn off support for binary packages altogether, 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:

Note: We provide best-effort support for archived package binaries for packages archived after October 9, 2017. We do not provide support for packages archived prior to October 9th, 2017.

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.

R Configuration Steps (Linux)¶

Prerequisites¶

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

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
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.
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 16.04 (Xenial) is enabled, users 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 OS, 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' ...

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

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:

```r
> 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"

R Configuration Steps (Windows)¶

Prerequisites¶

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

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.
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 checkpoint):

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.