Building and Publishing Binaries

Important

Make sure to read Requirements before proceeding here.

Build scenarios

Build scenarios depend on your environment and requirements:

1. Building all (historic) versions of a package
2. Building a single/latest version of a package

Both scenarios can be executed locally or remotely on a server.

Tip

When building locally frequently, use a Makefile or Justfile to simplify the build process. See the Justfile of the build-cran-binaries repo for inspiration.

Note

To understand the overall process and actions that will be performed, start with a local build of a single package version for one architecture/distribution. Scaling out and using remote builders is easier afterward.

Building binaries

The key function for building is bincraft::build_binary_package(). It has many arguments, making it flexible but also potentially overwhelming.

1. To build a functional binary, provide the build environment for your target architecture/distribution. The easiest approach is to use containers. This project curates multiple container images for building binaries. These images contain all necessary tools and libraries for each target architecture/distribution.

   The following images are available for both amd64 and arm64 across multiple R versions:

   • docker.io/devxygmbh/rpkgs-build-env-ubuntu
   • docker.io/devxygmbh/rpkgs-build-env-redhat
   • docker.io/devxygmbh/rpkgs-build-env-alpine

2. To understand the build process in detail, run the following command. This builds a binary for the R-only package brew from the CRAN repository. It does so in an Ubuntu 24.04 container without post-processing actions such as uploading or archival.

   docker run --rm devxygmbh/rpkgs-build-env-ubuntu:noble-4.4.3 \
     R -q -e "bincraft::build_binary_package('brew', archive = FALSE, upload = FALSE, tag = '1.0-10')"

   Caution

   While most R packages aren't sensitive to R minor versions, some are. Use the R version which you use in the projects the binary should be used in. A good approach is to use the latest patch version of the second last minor R version (e.g., if R 4.5.x is latest, use R 4.4.x).

To build from a Git source other than CRAN, set the url argument in build_binary_package(). For other arguments, see the function reference.

Important

build_binary_package() only builds binaries based on tags: all versions must be tagged in the referenced Git repository. Building binaries from HEAD or other heuristics is not currently supported.

Creating the package index

After binaries exist in S3, the repository index files must be created. These are used by install.packages() and related functions to determine which packages are available. Unfortunately, no canonical standard exists across all package installation functions. Therefore, multiple index files must be created:

• PACKAGES (used by install.packages())
• PACKAGES.rds (unclear)
• PACKAGES.gz (used by pak())
• PACKAGES.sqlite (used by pak())
• Meta/archive.rds (used by remotes::install_version())

Fortunately, {bincraft} and its dependencies (specifically {cranlike}) handle this automatically.
Running

upload_package_index(<args>)

creates/updates the files based on S3 bucket contents and uploads them to the appropriate locations.

Note

This action must be executed after every package change in the bucket.
Therefore, it is highly recommended to run this function on an automated schedule, e.g., daily.