R4R is a tool for creating a reproducible environment from a dynamic program trace.

Fill the survey about re-executability and reproducibility of R code ; it will help us improve r4r!

Article at ACM REP 2025

Download the r4r binary from the release page. Note that we currently only support Debian and Ubuntu. Other distribution will work as well, but files won't be resolved into packages, instead they will be simply copied.

Run the tool on a R notebook that outputs a HTML file:

r4r R -e "rmarkdown::render('path/to/notebook.Rmd')" --output output --result notebook.html

This will create an output directory with a Docker file, a Makefile, and other auxiliary files then build a Docker image.with tag r4r/test all the necessary data, R package, system package dependencies, and then run the Docker image as a container called r4r-test to re-execute the notebook. The result will be saved in output/result if you want to check if it is exactly reproducible.

You can skip the building of the Docker image by passing --skip-make to r4r. In that case, you will have to go to the output directory and run make build to build the Docker image and make copy to run it and get the result.

If you want to upload the image to a repository, you can use the docker push command:

docker push r4r/test

If you want to manually export the image to save it in some archive, you can do:

docker save r4r/test -o r4r-test.tar

You most likely want to compress that tar archive.

Clone the repository:

git clone [email protected]:r-tooling/r4r.git

Make sure you have a C++ compiler supporting at least C++21 and CMake.

Go into the r4r directory, compile and install:

cd r4r
make install BUILD_TYPE=Release

The built binary should be in build/r4r directory You're now good to go!

$ r4r --help
Usage: r4r [OPTIONS] <command>

Options:
  -v, --verbose                   Make the tool more talkative (allow multiple)
  --docker-image-tag NAME         The docker image tag [default: r4r/test]
  --docker-container-name NAME    The docker container name [default: r4r-test]
  --result PATH                   Path to a result file
  --output PATH                   Path for the output
  --help                          Print this message

Positional arguments:
  command    The program to trace

Have a a look at r4rwrapper.

Look at the Makefile:

$ make help
all                  Build and test the project (default)
configure            Configure CMake project
build                Build the project
test                 Run tests
coverage             Run tests with code coverage
install              Install the project
format               Format source code
lint                 Run static analysis
clean                Clean build artifacts
help                 Show this help message

Look at the .devcontainer/Dockerfile.

Integration tests can be run in two modes:

• local
• in docker container ghcr.io/r-tooling/r4r-it

make -C tests-integration <test_name> [LOCAL=1]

For example:

make -C tests-integration r-hello-world

If running in the local mode (LOCAL=1), make sure the project is built before. Also, make sure that you have all the dependencies the test requires (i.e. all the R packages). You can do that by trying a test run:

make -C tests-integration/r-hello-world test-run

Missing R packages could be installed using the setup target:

make -C tests-integration/r-hello-world setup

If running in the container, the makefile should built the container before running the test. The container could be built manually by

make -C tests-integration docker-image

The name of the test is the name of a directory inside the tests-integration directory. The r-kaggle can only run locally, as it would make the container too big

Note:

• The final check for the generated artifacts is rather simple, using a diff
• It is possible that a newer version of a library changes slightly how the generated artifact looks like (e.g., changes the JS code in the preamble of the HTML file).

• We try to follow Google C++ code style