Overview

basilisk.utils provides consistent access to conda via the Miniforge project for use in other Bioconductor packages. The idea is to check if an appropriate version of conda is already available on the host machine, and if not, download and install a local copy of conda managed by basilisk.utils. This avoids end-users having to manually install conda via SystemRequirements: conda. To find the conda binary:

basilisk.utils::find()

## [1] "/github/home/.cache/R/biocconda/24.11.3-0/bin/conda"

This will return either a conda command on the PATH (if it is of a suitable version) or the cached path to a conda executable after downloading the binaries (otherwise). Developers can use pass this to, e.g., reticulate’s conda_install() function to create a package-specific conda environment.

For package developers

When writing a Bioconductor package that relies on a conda environment, we create a file that defines all of the environments that we need. This is achieved by defining *_args variables, each of which is a list of arguments to pass to createEnvironment().

# environments.R 

env1_args <- list(
    pkg="my_package",
    name="env1",
    version="0.1.0", # doesn't have to be the same as the package version.
    packages="hdf5=1.14.6"
)

env2_args <- list(
    pkg="my_package",
    name="env2",
    version="0.2.0",
    packages="pandas" # version pinning is recommended, but not required.
)

We can now write our package functions that lazily create these environments on demand.

my_custom_function <- function() {
    path <- do.call(basilisk.utils::createEnvironment, env1_args)
    file.path(path, "bin", "h5ls")
}

Once the package is installed, the user’s first call to my_custom_function() will trigger the creation of the associated environment.

my_custom_function()

## [1] "/github/home/.cache/R/my_package/env1/0.1.0/bin/h5ls"

We also add a configure file to the root of the package directory. This will create all environments during R package installation if the BIOCCONDA_USE_SYSTEM_INSTALL environment variable is set. Administrators can subsequently bypass the lazy instantiation, e.g., for shared R installations on HPCs or within Docker images.

#!/bin/sh

${R_HOME}/bin/Rscript -e "basilisk.utils::configureEnvironments('R/environments.R')"

Also might as well do it for configure.win, so that it works on Windows as well:

#!/bin/sh

${R_HOME}/bin${R_ARCH_BIN}/Rscript.exe -e "basilisk.utils::configureEnvironments('R/environment.R')"

Package developers should also set StagedInstall: no to ensure that conda environments are created with the correct hard-coded paths within the R package installation directory.

Setting defaults

Most default behaviors of basilisk.utils are captured in the following functions, which can in turn be controlled by environment variables.

basilisk.utils::defaultCommand()

## [1] "conda"

basilisk.utils::defaultMinimumVersion()

## [1] "24.11.3"

basilisk.utils::defaultDownloadVersion()

## [1] "24.11.3-0"

basilisk.utils::defaultCacheDirectory()

## [1] "/github/home/.cache/R/biocconda"

For example:

Sys.setenv(BIOCCONDA_CONDA_MINIMUM_VERSION="25.3.0")
basilisk.utils::defaultMinimumVersion()

## [1] "25.3.0"

And, as mentioned previously, the BIOCCONDA_USE_SYSTEM_INSTALL environment variable determines whether the environments are created during R package installation.