Scenario: there’s a bug in the check results of your package on a CRAN Linux platform, or you saw such a bug even before CRAN submission, by building your package on a R-hub Linux platform. How can you reproduce and fix the bug? Submitting to the R-hub platform (or the R-hub platform that’s closest to the CRAN platform) after each tweak of your code would have a high turnaround so is not optimal for debugging. R-hub’s Linux Docker images are available for you to use, so you can run the R-hub Linux builders locally.
Warning: at the moment, the functions are not tested on Windows! Bug reports are welcome :-)
To be able to use the feature, you will need to install Docker.
Please refer to Docker
docs. On Windows, installation might be trickier, check that your
machine meets
the system requirements. On Linux, make sure to run the
post-installation steps to make the docker command
available to your user without the sudo prefix.
If you are new to Docker, for the basic use shown in the next two sections you don’t need to learn anything, you won’t have to leave R. Nonetheless, if you’re curious, this tutorial features a nice introduction. Also see this blog post and the list of resources it shows at the end.
Each of R-hub Linux platforms is associated to a Docker image, whose Dockerfile is stored in the r-hub/rhub-linux-builders repository, and that is built and available on Docker Hub. Note, if you’re used to using Docker images outside of R, you might want to just refer to the information in R-hub Linux Docker images GitHub repository (including links to the built images on Docker Hub). The advantage of using the rhub package instead of Docker directly, is that the package will install the system requirements properly.
To list the available images from R, you can use the
local_check_linux_images() function that returns a
data.frame and has a pretty default printing.
imgs <- local_check_linux_images()
imgs
#> rhub/debian-clang-devel:
#> Debian Linux, R-devel, clang, ISO-8859-15 locale
#> rhub/debian-gcc-devel:
#> Debian Linux, R-devel, GCC
#> rhub/debian-gcc-devel-nold:
#> Debian Linux, R-devel, GCC, no long double
#> rhub/debian-gcc-patched:
#> Debian Linux, R-patched, GCC
#> rhub/debian-gcc-release:
#> Debian Linux, R-release, GCC
#> rhub/fedora-clang-devel:
#> Fedora Linux, R-devel, clang, gfortran
#> rhub/fedora-gcc-devel:
#> Fedora Linux, R-devel, GCC
#> rhub/rocker-gcc-san:
#> Debian Linux, R-devel, GCC ASAN/UBSAN
#> rhub/ubuntu-gcc-devel:
#> Ubuntu Linux 20.04.1 LTS, R-devel, GCC
#> rhub/ubuntu-gcc-release:
#> Ubuntu Linux 20.04.1 LTS, R-release, GCC
#> rhub/ubuntu-rchk:
#> Ubuntu Linux 20.04.1 LTS, R-devel with rchk
knitr::kable(imgs, row.names = FALSE)| name | description | cran-name | rversion | os-type | cpu-type | os-info | compilers | docker-image | sysreqs-platform | categories | node-labels | queue | output-parser |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| debian-clang-devel | Debian Linux, R-devel, clang, ISO-8859-15 locale | r-devel-linux-x86_64-debian-clang | r-devel | Linux | x86_64 | Debian GNU/Linux testing | Debian clang version 11.0.1-2 | debian-clang-devel | linux-x86_64-debian-clang | Linux | linux | linux | NA |
| debian-gcc-devel | Debian Linux, R-devel, GCC | r-devel-linux-x86_64-debian-gcc | r-devel | Linux | x86_64 | Debian GNU/Linux testing | gcc (Debian 10.2.1-6) 10.2.1 20210110 | debian-gcc-devel | linux-x86_64-debian-gcc | Linux | linux | linux | NA |
| debian-gcc-devel-nold | Debian Linux, R-devel, GCC, no long double | NA | r-devel | Linux | x86_64 | Debian GNU/Linux testing | gcc (Debian 10.2.1-6) 10.2.1 20210110 | debian-gcc-devel-nold | linux-x86_64-debian-gcc | Linux | linux | linux | NA |
| debian-gcc-patched | Debian Linux, R-patched, GCC | r-patched-linux-x86_64 | r-patched | Linux | x86_64 | Debian GNU/Linux testing | gcc (Debian 10.2.1-6) 10.2.1 20210110 | debian-gcc-patched | linux-x86_64-debian-gcc | Linux | linux | linux | NA |
| debian-gcc-release | Debian Linux, R-release, GCC | r-release-linux-x86_64 | r-release | Linux | x86_64 | Debian GNU/Linux testing | gcc (Debian 10.2.1-6) 10.2.1 20210110 | debian-gcc-release | linux-x86_64-debian-gcc | Linux | linux | linux | NA |
| fedora-clang-devel | Fedora Linux, R-devel, clang, gfortran | r-devel-linux-x86_64-fedora-clang | r-devel | Linux | x86_64 | Fedora 33 | clang version 11.0.0 (Fedora 11.0.0-2.fc33) | fedora-clang-devel | linux-x86_64-fedora-clang | Linux | linux | linux | NA |
| fedora-gcc-devel | Fedora Linux, R-devel, GCC | r-devel-linux-x86_64-fedora-gcc | r-devel | Linux | x86_64 | Fedora 33 | gcc (GCC) 10.2.1 20201125 (Red Hat 10.2.1-9) | fedora-gcc-devel | linux-x86_64-fedora-gcc | Linux | linux | linux | NA |
| linux-x86_64-rocker-gcc-san | Debian Linux, R-devel, GCC ASAN/UBSAN | NA | r-devel | Linux | x86_64 | Debian GNU/Linux testing | GCC 5.4.0 (Debian 5.4.0-4) | rocker-gcc-san | linux-x86_64-debian-gcc | Checks for compiled code | linux | linux | sanitizers |
| ubuntu-gcc-devel | Ubuntu Linux 20.04.1 LTS, R-devel, GCC | NA | r-devel | Linux | x86_64 | Ubuntu 20.04.1 LTS | gcc (Ubuntu 9.3.0-17ubuntu1~20.04) 9.3.0 | ubuntu-gcc-devel | linux-x86_64-ubuntu-gcc | Linux | linux | linux | NA |
| ubuntu-gcc-release | Ubuntu Linux 20.04.1 LTS, R-release, GCC | NA | r-release | Linux | x86_64 | Ubuntu 20.04.1 LTS | gcc (Ubuntu 9.3.0-17ubuntu1~20.04) 9.3.0 | ubuntu-gcc-release | linux-x86_64-ubuntu-gcc | Linux | linux | linux | NA |
| ubuntu-rchk | Ubuntu Linux 20.04.1 LTS, R-devel with rchk | NA | r-devel | Linux | x86_64 | Ubuntu 20.04.1 LTS | clang version 12.0.0-3ubuntu1~20.04.5 | ubuntu-rchk | linux-x86_64-ubuntu-gcc | Checks for compiled code | linux | linux | rchk |
Of particular interest are
the cranname columns if you’re trying to find an
equivalent to a CRAN platform;
the name platform which is the ID you should use to
select that platform.
In theory, you could also use images that are not listed in the list above, e.g. your own Docker images.
Below we’ll start a check of a package on the “rhub/debian-gcc-release” image (Debian Linux, R-release, GCC). The first time you use an image on your machine, it’ll be downloaded from Docker Hub, which might take a while. The image won’t be deleted after use, so next time will be faster until you clean up your machine’s Docker images, which one should do once in a while (note that R-hub images are regularly updated).
pkg_path <- "/home/maelle/Documents/R-hub/test-packages/note"
local_check_linux(pkg_path, image = "rhub/debian-gcc-release")You can either just run the check as shown above, which will print a
log to the screen, including R CMD check results in the
end, or assign it to an object:
pkg_path <- "/home/maelle/Documents/R-hub/test-packages/note"
chk <- local_check_linux(pkg_path, image = "rhub/debian-gcc-release")The object returned is of the class rcmdcheck::rcmdcheck
which is an S3 object with fields errors,
warnings and notes (character vectors), that
you could operate on if you wish.
The local_check_linux() function creates a container
(instance of the image) that won’t be deleted after use so you might
want to clean up once in a while.
If running checks in images iteratively isn’t enough for your
debugging, you might want to run the container created by
local_check_linux(). Take note of the container name and
run (in a shell, not in R)
docker container start 7181196d-bc3c-4fc8-a0e8-dc511150335d-2
docker exec -it 7181196d-bc3c-4fc8-a0e8-dc511150335d-2 bashwhere 7181196d-bc3c-4fc8-a0e8-dc511150335d-2 is the
container name, this is printed out by local_check_linux().
After running these commands, you will get a shell within the Docker
container, where you can run R. Note that on some containers R is
installed in /opt/.
For more information, you may want to look at the shell script that
rhub uses to set up the container for running the check. To
find it, run the code below.
system.file(package = "rhub", "bin", "rhub-linux-docker.sh")
#> [1] "/home/runner/work/_temp/Library/rhub/bin/rhub-linux-docker.sh"