From 60fef4c6d2eea1b06859ca1a406558fdccc2112f Mon Sep 17 00:00:00 2001 From: Iñaki Úcar Date: Jan 08 2026 15:35:24 +0000 Subject: clarifications and minor fixes --- diff --git a/guidelines/modules/ROOT/pages/R.adoc b/guidelines/modules/ROOT/pages/R.adoc index 22a7004..7abc3ed 100644 --- a/guidelines/modules/ROOT/pages/R.adoc +++ b/guidelines/modules/ROOT/pages/R.adoc @@ -72,6 +72,13 @@ Packages from the following repositories *MUST* use the set macros provided for * CRAN: `+%{cran_url}+` and `+%{cran_source}+` * Bioc: `+%{bioc_url}+` and `+%{bioc_source}+` +The URLs above correspond to the default _software_ repositories. +Bioconductor provides additional repositories that can be specified via an argument: + +* AnnotationData: `+%{bioc_url data/annotation}+` and `+%{bioc_source data/annotation}+` +* ExperimentData: `+%{bioc_url data/experiment}+` and `+%{bioc_source data/experiment}+` +* Workflows: `+%{bioc_url workflows}+` and `+%{bioc_source workflows}+` + == Architectures Packages that do not contain architecture-specific code (i.e. no compiled parts), *MUST* set `BuildArch: noarch`. @@ -118,8 +125,7 @@ Build-time dependencies on other R packages are automatically handled by the `+% [NOTE] ==== * All hard dependencies (R's `LinkingTo`, `Depends`, `Imports`) are declared as `BuildRequires` using standardized names (see <>). -* Soft dependencies (R's `Suggests`, `Enhances`) are skipped, except for packages used to develop the test suite -(currently, `testthat`, `tinytest` or `RUnit`). +* Soft dependencies (R's `Suggests`, `Enhances`) are skipped, except for packages used to develop the test suite (see <>). ==== === Bundled dependencies @@ -131,7 +137,7 @@ Whenever bundled dependencies are used, they *MUST* be declared with virtual `Pr Some R packages expose header files under the standard path `R/library/$pkg/include` (defined by CRAN and expected by R), so that other packages can link to them via `LinkingTo`. The https://cran.r-project.org/package=Rcpp[Rcpp] package is a notable example. -Sometimes, these headers are required at build-time, sometimes at build- as well as run-time and therefore they are essential for proper functioning... +Sometimes, these headers are required at build-time, sometimes at build- as well as run-time and therefore they are essential for proper functioning. For these and a variety of other reasons, these headers *MUST NOT* be split off into a `-devel` sub-package. If a particular package contains a large number of examples or documentation that do not impact the package's functionality, these parts *MAY* be split off into a sub-package, @@ -160,7 +166,24 @@ The `+%R_buildrequires+` macro *MUST* be called in the `+%generate_buildrequires %R_buildrequires ---- -Testing packages such as `testthat`, which are declared in `Suggests` are whitelisted in `+%{__R_whitelist}+`, and added as `BuildRequires` by `+%R_buildrequires+`. +Testing packages such as `testthat`, which are declared in `Suggests`, are whitelisted in `+%{__R_whitelist}+`, +and added as `BuildRequires` by `+%R_buildrequires+`. + +[IMPORTANT] +==== +Currently, only the most common testing suites available in Fedora are supported: + +`testthat|tinytest|RUnit|testit` +==== + +Using other `Suggests` in the tests *SHOULD* be considered a bug. +However, some additional `Suggests` *MAY* be used by overwriting `+%{__R_whitelist}+` as follows: + +---- +%global __R_whitelist testthat|mockery|withr +---- + +if the packager wishes to use `mockery` and `withr` on top of `testthat`. === Building and Installing @@ -168,7 +191,7 @@ R packages are built and installed in a single stage via `R CMD INSTALL`. Therefore, the `+%build+` section *MUST* be empty. Two macros are provided and *MUST* be called in the `+%install+` section. -First, `+%R_install+` builds and installs the package, +First, `+%R_install+` builds and installs the package into `+%{buildroot}%{_R_libdir}+`, then `+%R_save_files+` generates a list of files corresponding to the given importable module, and saves it as `+%{R_files}+`. ---- @@ -195,7 +218,7 @@ The `+%R_install+` macro deletes this file. The `+%R_install+` macro calls `+%_R_libdir_check+` to ensure that a noarch package did not produce a shared library, or an archful package actually contains a shared library; otherwise, it fails with an informative error message. -If the packager does not want this check, `+%_R_libdir_check+` can be set e.g. to an empty string. +If the packager does not want this check, `+%_R_libdir_check+` *MAY* be set to `+%nil+`. ==== === Testing @@ -211,10 +234,10 @@ According to CRAN’s guidelines, R packages *MUST* work without soft dependenci If package checks fail because soft dependencies are used unconditionally (e.g. in examples or tests), this is considered a bug and *SHOULD* be reported upstream. Meanwhile, a workaround *MUST* be put in place: -* If the failure happens in an example, the `--no-examples` flag *MAY* be appended to `+%R_check+`. +* If the failure happens in an example, the `\--no-examples` flag *MAY* be appended to `+%R_check+`. * If the failure happens in a test, a `skip()` call *MAY* be added in the proper place to skip a test, or a test file *MAY* be removed, -or even the `--no-tests` flag *MAY* be appended to `+%R_check+` for more complicated situations. +or even the `\--no-tests` flag *MAY* be appended to `+%R_check+` for more complicated situations. === Listing files