Force version of Bioconductor in use to env. variable R_BIOC_VERSION

R/BiocManager-package.R

@@ -4,6 +4,10 @@ NULL
 
 #' Install or update Bioconductor, CRAN, or GitHub packages
 #'
+#' @aliases R_BIOC_VERSION
+#'
+#' @description
+#'
 #' This package provides tools for managing _Bioconductor_ and other
 #' packages in a manner consistent with _Bioconductor_'s package
 #' versioning and release system.
@@ -66,6 +70,11 @@ NULL
 #' - \env{BIOCMANAGER_SITE_REPOSITORY} configure a more permanent
 #'   `site_repository` input to `repositories()`. See `?repositories`.
 #'
+#' - \env{R_BIOC_VERSION} use a specific, possibly unsupported,
+#'   version of Bioconductor. `install()`, `version()`, `available()`,
+#'   `valid()`, and `repositories()` all use the version *without*
+#'   checking that it is consistent with the version of *R* in use.
+#'
 #' @md
 #' @aliases BiocManager
 #'

R/install.R

@@ -394,9 +394,12 @@ install <-
 
     version <- .version_validate(version)
 
+    ## use BiocVersion if .version_force_version() is not set;
+    ## `BiocVersion_pkg` is either "BiocVersion" or NULL.
+    BiocVersion_pkg <- if (is.na(.version_force_version())) "BiocVersion"
     inst <- installed.packages()
     if (!"BiocVersion" %in% rownames(inst)) {
-        pkgs <- unique(c("BiocVersion", pkgs))
+        pkgs <- unique(c(BiocVersion_pkg, pkgs))
     }
 
     cmp <- .version_compare(version, version())
@@ -408,7 +411,7 @@ install <-
         site_repository = site_repository)
 
     if (cmp != 0L) {
-        pkgs <- unique(c("BiocVersion", pkgs))
+        pkgs <- unique(c(BiocVersion_pkg, pkgs))
         valist <- .valid_result(vout, pkgs = inst)
         npkgs <- .install_n_invalid_pkgs(valist) + length(pkgs)
         if (!length(pkgs)-1L) {

R/version.R

@@ -35,6 +35,22 @@
     )
 )
 
+## version-specific options
+
+.version_force_version <-
+    function()
+{
+    ## check R_BIOC_VERSION environment variable
+    force_version <- Sys.getenv("R_BIOC_VERSION", "")
+
+    ## return either NA (do no force version) or the version to use
+    if (nzchar(force_version)) {
+        package_version(force_version)
+    } else {
+        NA
+    }
+}
+
 .version_sentinel <-
     function(msg)
 {
@@ -259,6 +275,12 @@ format.version_sentinel <-
     function(version, map = .version_map(), r_version = .version_R_version(),
              check_future = FALSE)
 {
+    if (!is.na(.version_force_version())) {
+        return(sprintf(
+            "Using environment variable R_BIOC_VERSION = '%s'",
+            version
+        ))
+    }
     if (identical(version, "devel"))
         version <- .version_bioc("devel")
     version <- .package_version(version)
@@ -319,6 +341,9 @@ format.version_sentinel <-
     if (identical(version, "devel"))
         version <- .version_bioc("devel")
     version <- .package_version(version)
+    force_version <- .version_force_version()
+    if (identical(version, force_version))
+        return(version)
 
     txt <- .version_validity(version)
     isTRUE(txt) || ifelse(.is_CRAN_check(), .message(txt), .stop(txt))
@@ -427,6 +452,10 @@ format.version_sentinel <-
 #' when version cannot be validated e.g., because internet access is
 #' not available.
 #'
+#' The environment variable `R_BIOC_VERSION` can be used to specify a
+#' version that is not consistent with *Bioconductor* release
+#' versioning. Use of this variable is strongly discouraged.
+#'
 #' @return A two-digit version, e.g., `3.8`, of class
 #'     `package_version` describing the version of _Bioconductor_ in
 #'     use.
@@ -439,7 +468,9 @@ format.version_sentinel <-
 version <-
     function()
 {
-    bioc <- .version_BiocVersion()
+    bioc <- .version_force_version()
+    if (is.na(bioc))
+        bioc <- .version_BiocVersion()
     if (is.na(bioc))
         bioc <- .version_choose_best()
 

tests/testthat/test_version.R

@@ -418,8 +418,63 @@ test_that("version chooses best", {
             target_version
         },
         expect_identical(
-            version(),
+            .version_choose_best(),
             target_version
         )
     )
 })
+
+test_that(".version_force_version() works", {
+    skip_if_offline()
+
+    test_version <- "3.16"
+    withr::with_envvar(
+        list(R_BIOC_VERSION = ""),
+        expect_false(identical(version(), package_version(test_version)))
+    )
+    withr::with_envvar(
+        list(R_BIOC_VERSION = ""),
+        expect_true(is.na(.version_force_version()))
+    )
+    withr::with_envvar(
+        list(R_BIOC_VERSION = test_version),
+        expect_identical(
+            .version_force_version(), package_version(test_version)
+        )
+    )
+    withr::with_envvar(
+        list(R_BIOC_VERSION = test_version),
+        expect_identical(version(), package_version(test_version))
+    )
+    withr::with_envvar(
+        list(R_BIOC_VERSION = test_version),
+        expect_identical(
+            .version_validate(test_version),
+            package_version(test_version)
+        )
+    )
+    withr::with_envvar(
+        list(R_BIOC_VERSION = test_version),
+        expect_identical(grep(test_version, repositories()), 1:5)
+    )
+
+    new_lib <- tempfile(); dir.create(new_lib)
+    withr::local_libpaths(new_lib)
+    expect_error(packageVersion("BiocVersion", lib.loc = .libPaths()[1]))
+    ## do *not* install BiocVersion
+    withr::with_envvar(list(R_BIOC_VERSION = test_version), install())
+    expect_error(packageVersion("BiocVersion", lib.loc = .libPaths()[1]))
+    ## install BiocVersion for original version
+    original_version <- version()
+    install("BiocVersion", lib = .libPaths()[1])
+    vers <- packageVersion("BiocVersion", lib.loc = .libPaths()[1])
+    expect_identical(
+        package_version(paste(vers$major, vers$minor, sep = ".")),
+        original_version
+    )
+    ## BiocVersion ignored with R_BIOC_VERSION
+    withr::with_envvar(
+        list(R_BIOC_VERSION = test_version),
+        expect_identical(version(), package_version(test_version))
+    )
+})

vignettes/BiocManager.Rmd

@@ -244,6 +244,30 @@ Error: Bioconductor version '3.9' requires R version '3.6'; see
 A special version, `version="devel"`, allows use of _Bioconductor_
 packages that are under development.
 
+## Unsupported *R* / *Bioconductor* versions
+
+The main purpose of BiocManager is to ensure that users install the
+version of *Bioconductor* appropriate for their version of *R*. Use
+the environment variable `R_BIOC_VERSION` to install any version of
+*Bioconductor* on any version of *R*. Thus *R* version 4.3.0 and
+*Bioconductor* version 3.19 are not compatible...
+
+```
+> BiocManager::install(version = "3.19")
+Error: Bioconductor version '3.19' requires R version '4.4'; use
+  `version = '3.18'` with R version 4.3; see
+  https://bioconductor.org/install
+```
+
+...but the version can be forced with
+
+```
+> Sys.setenv(R_BIOC_VERSION="3.19")
+> BiocManager::install(version = "3.19")
+...
+Bioconductor version 3.19 (BiocManager 1.30.23), R 4.3.0 (2023-04-21)
+```
+
 ## Managing multiple versions {#multiple-versions}
 
 It is possible to have multiple versions of _Bioconductor_ installed on the