Skip to content

Latest commit

 

History

History
244 lines (192 loc) · 9.01 KB

README.md

File metadata and controls

244 lines (192 loc) · 9.01 KB
Raw

rix: Reproducible Environments with Nix

R-hub v2 CRAN runiverse-package rix Docs Status at rOpenSci Software Peer Review

Introduction

{rix} is an R package that leverages Nix, a package manager focused on reproducible builds. With Nix, you can create project-specific environments with a custom version of R, its packages, and all system dependencies (e.g., GDAL). Nix ensures full reproducibility, which is crucial for research and development projects.

Use cases include running web apps (e.g., Shiny, {plumber} APIs) or {targets} pipelines with a controlled R environment. Unlike {renv}, which snapshots package versions, {rix} provides an entire ecosystem snapshot, including system-level dependencies.

Important sidenote: as it so happened, there is currently a bug in the released CRAN version that we thought we had solved, which we did, but only partially. When running rix::rix() two files should be generated: a default.nix and an .Rprofile for your project. It turns out that this file can be empty. If it is, run rix::rix_init(rprofile_action = "overwrite") to generate a proper .Rprofile. This is important, especially on Mac or if you have a system-wide library of packages! We will submit a fix asap.

While Nix has a steep learning curve, {rix}

  1. simplifies creating Nix expressions, which define reproducible environments.
  2. lets you work interactively in IDEs like RStudio or VS Code, or use Nix in CI/CD workflows.
  3. provides helpers that make it easy to build those environments, evaluate the same code in different development environments, and finally to deploy software environments in production.

If you want to watch a 5-Minute video introduction click here.

Nix includes nearly all CRAN and Bioconductor packages, with the ability to install specific package versions or GitHub snapshots. Nix also includes Python, Julia (and many of their respective packages) as well as many, many other tools (up to 100’000 pieces of software as of writing).

If you have R installed, you can start straight away from your R session by first installing {rix}:

install.packages("rix", repos = c(
  "https://ropensci.r-universe.dev",
  "https://cloud.r-project.org"
))
library("rix")

Now try to generate an expression using rix():

# Choose the path to your project
# This will create two files: .Rprofile and default.nix
path_default_nix <- "."

rix(
  r_ver = "4.3.3",
  r_pkgs = c("dplyr", "ggplot2"),
  system_pkgs = NULL,
  git_pkgs = NULL,
  ide = "code",
  project_path = path_default_nix,
  overwrite = TRUE,
  print = TRUE
)

This will generate two files, default.nix and .Rprofile in project_default_nix. default.nix is the environment definition written in the Nix programming language, and .Rprofile prevents conflicts with library paths from system-installed R versions, offering better control over your environment and improving isolation of Nix environments. .Rprofile is created by rix_init() which is called automatically by the main function, rix().

Quick Start for Returning Users

Click to expand

If you’re already familiar with Nix and {rix}, install Nix using the Determinate Systems installer:

curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install

You can then use {rix} to build and enter a Nix-based R environment:

library(rix)

path_default_nix <- "."

rix(
  r_ver = "4.3.3",
  r_pkgs = c("dplyr", "ggplot2"),
  system_pkgs = NULL,
  git_pkgs = NULL,
  ide = "code",
  project_path = path_default_nix,
  overwrite = TRUE,
  print = TRUE
)
# nix_build() is a wrapper around the command line tool `nix-build`
nix_build(project_path = ".")

If you don’t have R installed, but have the Nix package manager installed, you can run a temporary R session with R using this command (it will build an environment with the latest development version of {rix} ):

nix-shell --expr "$(curl -sl https://raw.githubusercontent.com/ropensci/rix/main/inst/extdata/default.nix)"

You can then create new development environment definitions, build them, and start using them.

Getting started for new users

New to {rix} and Nix? Start by reading the vignette("a-getting-started") (online documentation). to learn how to set up and use Nix smoothly.

Docker

Try Nix inside Docker by following this vignette("z-advanced-topic-using-nix-inside-docker") vignette.

How is Nix different from Docker+renv/{groundhog}/{rang}/(Ana/Mini)Conda/Guix? or Why Nix?

Docker + {renv}

Docker and {renv} provide robust reproducibility by combining package snapshots with system-level dependencies. However, for long-term reproducibility, Nix offers a simpler approach by bundling everything (R, packages, and dependencies) in a single environment.

Ana/Miniconda & Mamba

Conda is similar to Nix, but Nix offers immutable environments, making it more reliable for preventing accidental changes. Nix also supports nearly all CRAN and Bioconductor packages, which Conda lacks.

Nix vs. Guix

Guix, like Nix, focuses on reproducibility, but Nix supports more CRAN/Bioconductor packages and works across Windows, macOS, and Linux.

Is {rix} all there is?

No, there are other tools that you might want to check out, especially if you want to set up polyglot environments (even though it is possible to use {rix} to set up an environment with R and Python packages for example).

Take a look at https://devenv.sh/ and https://prefix.dev/ if you want to explore other tools that make using Nix easier!

Contributing

Refer to Contributing.md to learn how to contribute to the package.

Please note that this package is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.

Thanks

Thanks to the Nix community for making Nix possible, and thanks to the community of R users on Nix for their work packaging R and CRAN/Bioconductor packages for Nix (in particular Justin Bedő, Rémi Nicole, nviets, Chris Hammill, László Kupcsik, Simon Lackerbauer, MrTarantoga and every other person from the Matrix Nixpkgs R channel).

Finally, thanks to David Solito for creating {rix}’s logo!

Recommended reading