packaging/guidelines
6
2
Fork 15
Code Issues 112 Pull requests 28 Projects Releases Packages Wiki Activity Actions

Merge #1516 R guidelines: clarifications and minor fixes

Browse source
This commit is contained in:
James Antill 2026-01-08 16:58:42 +00:00
commit 915b98fdc4
1 changed files with 31 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

39
guidelines/modules/ROOT/pages/R.adoc
View file

@ -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 <<Automatic standardized names>>).
* 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 <<Dynamic BuildRequires>>).
====
=== 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