From 68f52aa3550c6d972308decb04286048bb6cc219 Mon Sep 17 00:00:00 2001 From: Martin Morgan Date: Tue, 16 Apr 2024 13:43:41 -0400 Subject: [PATCH 1/6] allow environment variable R_BIOC_VERSION to force Bioconductor version --- R/BiocManager-package.R | 9 +++++++++ R/install.R | 7 +++++-- R/version.R | 27 ++++++++++++++++++++++++++- man/BiocManager-package.Rd | 5 +++++ man/version.Rd | 4 ++++ 5 files changed, 49 insertions(+), 3 deletions(-) diff --git a/R/BiocManager-package.R b/R/BiocManager-package.R index f81cc440..fb2cc3c9 100644 --- a/R/BiocManager-package.R +++ b/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 #' diff --git a/R/install.R b/R/install.R index ccd72db2..e681b9d5 100644 --- a/R/install.R +++ b/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) { diff --git a/R/version.R b/R/version.R index f72d23e4..52899999 100644 --- a/R/version.R +++ b/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) { @@ -316,6 +332,9 @@ format.version_sentinel <- .version_validate <- function(version) { + force_version <- .version_force_version() + if (identical(package_version(version), force_version)) + return(version) if (identical(version, "devel")) version <- .version_bioc("devel") version <- .package_version(version) @@ -427,6 +446,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 +462,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() diff --git a/man/BiocManager-package.Rd b/man/BiocManager-package.Rd index 51589345..cfa23c45 100644 --- a/man/BiocManager-package.Rd +++ b/man/BiocManager-package.Rd @@ -3,6 +3,7 @@ \docType{package} \name{BiocManager-package} \alias{BiocManager-package} +\alias{R_BIOC_VERSION} \alias{BiocManager} \title{Install or update Bioconductor, CRAN, or GitHub packages} \description{ @@ -58,6 +59,10 @@ installations. See \code{?containerRepository}. non-standard CRAN or Bioconductor repositories. See \code{?repositories}. \item \env{BIOCMANAGER_SITE_REPOSITORY} configure a more permanent \code{site_repository} input to \code{repositories()}. See \code{?repositories}. +\item \env{R_BIOC_VERSION} use a specific, possibly unsupported, +version of Bioconductor. \code{install()}, \code{version()}, \code{available()}, +\code{valid()}, and \code{repositories()} all use the version \emph{without} +checking that it is consistent with the version of \emph{R} in use. } } \examples{ diff --git a/man/version.Rd b/man/version.Rd index 80ec20d1..7ed60014 100644 --- a/man/version.Rd +++ b/man/version.Rd @@ -30,6 +30,10 @@ by the user. \code{version()} (and all functions requiring version information) fails when version cannot be validated e.g., because internet access is not available. + +The environment variable \code{R_BIOC_VERSION} can be used to specify a +version that is not consistent with \emph{Bioconductor} release +versioning. Use of this variable is strongly discouraged. } \examples{ BiocManager::version() From add147edd8c5f19ac64bbae136c491847f87a3b6 Mon Sep 17 00:00:00 2001 From: Martin Morgan Date: Tue, 16 Apr 2024 16:18:41 -0400 Subject: [PATCH 2/6] new unit tests for R_BIOC_VERSION / .version_force_version() --- tests/testthat/test_version.R | 52 +++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/tests/testthat/test_version.R b/tests/testthat/test_version.R index 7c86bcd1..2e7fa5c1 100644 --- a/tests/testthat/test_version.R +++ b/tests/testthat/test_version.R @@ -423,3 +423,55 @@ test_that("version chooses best", { ) ) }) + +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), 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)) + ) +}) From 948a11b040ffeeb88eada94b52baa68b512eece1 Mon Sep 17 00:00:00 2001 From: Martin Morgan Date: Tue, 16 Apr 2024 16:28:46 -0400 Subject: [PATCH 3/6] update existing unit tests for R_BIOC_VERSION / .version_force_version() --- tests/testthat/test_version.R | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/testthat/test_version.R b/tests/testthat/test_version.R index 2e7fa5c1..2617ea1a 100644 --- a/tests/testthat/test_version.R +++ b/tests/testthat/test_version.R @@ -418,7 +418,7 @@ test_that("version chooses best", { target_version }, expect_identical( - version(), + .version_choose_best(), target_version ) ) From c7f434fa77a823635079eadf1ddf0837f25482f3 Mon Sep 17 00:00:00 2001 From: Martin Morgan Date: Fri, 10 May 2024 12:45:09 -0400 Subject: [PATCH 4/6] translate 'devel' to version before version comparison --- R/version.R | 6 +++--- tests/testthat/test_version.R | 5 ++++- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/R/version.R b/R/version.R index 52899999..59d6d711 100644 --- a/R/version.R +++ b/R/version.R @@ -332,12 +332,12 @@ format.version_sentinel <- .version_validate <- function(version) { - force_version <- .version_force_version() - if (identical(package_version(version), force_version)) - return(version) 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)) diff --git a/tests/testthat/test_version.R b/tests/testthat/test_version.R index 2617ea1a..541a0a21 100644 --- a/tests/testthat/test_version.R +++ b/tests/testthat/test_version.R @@ -448,7 +448,10 @@ test_that(".version_force_version() works", { ) withr::with_envvar( list(R_BIOC_VERSION = test_version), - expect_identical(.version_validate(test_version), test_version) + expect_identical( + .version_validate(test_version), + package_version(test_version) + ) ) withr::with_envvar( list(R_BIOC_VERSION = test_version), From 4ad0449611ae48e46c342c5c1e03d06f31145825 Mon Sep 17 00:00:00 2001 From: Martin Morgan Date: Fri, 10 May 2024 12:46:23 -0400 Subject: [PATCH 5/6] note use of R_BIOC_VERSION when attaching BiocManager --- R/version.R | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/R/version.R b/R/version.R index 59d6d711..5eb53baf 100644 --- a/R/version.R +++ b/R/version.R @@ -275,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) From 43d206277f1f36f1d6b5b65b4084cf05c8ed76e3 Mon Sep 17 00:00:00 2001 From: Martin Morgan Date: Fri, 10 May 2024 12:59:48 -0400 Subject: [PATCH 6/6] add vignette section documenting R_BIOC_VERSION --- vignettes/BiocManager.Rmd | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/vignettes/BiocManager.Rmd b/vignettes/BiocManager.Rmd index d8a18f8b..b4a4b881 100644 --- a/vignettes/BiocManager.Rmd +++ b/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